fbdocs: wiki snapshot 2023.05.14

- update changed examples

Author: jayrm

doc/manual/cache/DevBuildConfig.wakka

@@ -131,5 +131,8 @@ make install-rtlib install-gfxlib2 TARGET=i686-w64-mingw32
 	- ##-DDISABLE_OPENGL##
 		With this, the gfxlib2 will not use ""OpenGL"" headers, disabling the ""OpenGL"" graphics drivers.
 
+{{fbdoc item="see"}}
+	- [[DevBuildOptions|FreeBASIC Build Options]]
+
 {{fbdoc item="back" value="DevToc|FreeBASIC Developer Information"}}
 {{fbdoc item="back" value="DocToc|Table of Contents"}}

doc/manual/cache/KeyPgAny.wakka

@@ -21,7 +21,7 @@ The ##**Any**## keyword is used as a placeholder for a type or value in various
 	[[KeyPgOpProcptr|Procptr]] ( //identifier//, [[[KeyPgVirtual|Virtual]]] **Any** )
 ##
 {{fbdoc item="desc"}}
-	- Pointers:
+	- Pointers (1st syntax):
 		A special pointer type called the ##**Any** [[KeyPgPtr|Ptr]]## (or "##**Any** [[KeyPgPtr|Pointer]]##") allows pointing to any variable type.  If you cast it to a ##//[[DataType]]// [[KeyPgPtr|Ptr]]##, it can be indexed or dereferenced to access the memory as an instance of ##//[[DataType]]//##. Pointer arithmetic is allowed on an ##**Any** Ptr##, and treats it like a ##[[KeyPgByte|Byte]] Ptr##: The pointer is changed by increments of ##1##.
 
 		A pure ##**Any** [[KeyPgPtr|Ptr]]## has no type checking by the compiler.  It can be implicitly converted to and from other pointer types through assignment or parameter passing.
@@ -30,27 +30,27 @@ The ##**Any**## keyword is used as a placeholder for a type or value in various
 
 		This should not be confused with ##**Variant**##, a Visual Basic data type which can contain any type of variable. ""FreeBASIC"" does not provide native support for a ##**Variant**## type.
 
-	- Byref parameters:
+	- Byref parameters (2nd syntax):
 		**##Any##** can be used in procedure prototypes (in a ##[[KeyPgDeclare|Declare]]## statement) with ##[[KeyPgByref|ByRef]]## parameters to disable the compiler checking for the correct type of the variable passed (this includes the array parameters because always implicitly passed by reference).
 		However, it does not work with UDT member procedures, except if they are static procedures.
 		This use of ##**Any**## is deprecated and it only exists for compatibility with QB.
 
-	- Array dimensions:
+	- Array dimensions (3rd/4th syntax):
 		In array declarations, **##Any##** can be specified in place of the array bounds in order to create a dynamic array with a certain amount of dimensions that is determined based on the number of **##Any##**s specified (use the syntax with **##Any##** is mandatory when declaring a dynamic array member inside a ##[[KeyPgType|Type]]##).
 
 		In parameter declarations, **##Any##** can be also specified instead of empty parenthesis in order to fix the amount of dimensions.
 
-	- Initialization:
+	- Initialization (5th/6th/7th syntax):
 		##**Any**## can be used as a fake initializer to disable the default initialization of variables to ##0##, leaving the variable uninitialized. This may save time in critical sections of a program. It is the program's responsibility to fill the variables with meaningful data before reading it.
 
 		Comparison to ""C/C++"": This matches the behavior of a variable declaration without initialization value in ""C/C++"".
 
 		Similar to **##Any##** initializers for variables, **##Any##** can also be used with the ##[[KeyPgOpNew|New Expression]]## or ##[[KeyPgOpPlacementNew|Placement New]]## operators in order to leave the newly created object uninitialized (only allowed with data types that do not have constructors).
 
-	- ""Instr/InstrRev"":
+	- ""Instr/InstrRev"" (8th syntax):
 		**##Any##** can be used with ##[[KeyPgInstr|Instr]]## or ##[[KeyPgInstrrev|InstrRev]]## as a qualifier for the ##//substring//## parameter, to indicate that any individual character in it may be matched.
 
-	- Procptr:
+	- Procptr (9th syntax):
 		**##Any##**, ie any procedure signature, does not induce any particular selection (compared to its non-use), but just allows for writing ##[[KeyPgOpProcptr|Procptr]]## always with 2 arguments.
 
 {{fbdoc item="ex"}}

doc/manual/cache/KeyPgOpProcptr.wakka

@@ -157,41 +157,59 @@ Print
 Sleep
 %%
 	{{fbdoc item="filename" value="examples/manual/operator/procptr4.bas"}}%%(freebasic)
-' Since fbc 1.10.0, ProcPtr allows to access the vtable index of a virtual/abstract member procedure/operator
+' Since fbc 1.10.0, ProcPtr also allows to access the vtable index of a virtual/abstract member procedure/operator
 
 Type Parent Extends Object
-	Declare Abstract Sub test()
+	Declare Abstract Sub VirtualTest()
 	Declare Virtual Operator Cast() As String
+	Declare Sub NormalTest()
 End Type
 
 Operator Parent.Cast() As String
 	Return "Parent.Cast() As String"
 End Operator
 
+Sub Parent.NormalTest()
+	Print "Parent.NormalTest()"
+End Sub
+
 Type Child Extends Parent
-	Declare Virtual Sub test()                 '' or Declare Sub test()
+	Declare Virtual Sub VirtualTest()          '' or Declare Sub test()
 	Declare Virtual Operator Cast() As String  '' or Declare Operator Cast() As String
+	Declare Sub NormalTest()
 End Type
 
-Sub Child.test()
-	Print "Child.test()"
+Sub Child.VirtualTest()
+	Print "Child.VirtualTest"
 End Sub
 
 Operator Child.Cast() As String
-	Return "Child.Ccast() As String"
+	Return "Child.Cast() As String"
 End Operator
 
+Sub Child.NormalTest()
+	Print "Child.NormalTest()"
+End Sub
+
 Dim As Parent Ptr p = New Child
-p->test()
+
+(*p).VirtualTest()      '' or p->VirtualTest()
 Print Cast(Parent, *p)  '' or Print *p
+(*p).NormalTest()       '' or p->NormalTest()
 Print
 
-#define VirtProcPtr(instance, procedure) CPtr(TypeOf(ProcPtr(procedure)), _       '' pointer to virtual procedure
-											CPtr(Any Ptr Ptr Ptr, @(instance)) _  '' (the most derived override that exists)
-											[0][ProcPtr(procedure, Virtual)])
-
-VirtProcPtr(*p, Parent.test)(*p)        '' execute p->test() through its vtable index
-Print VirtProcPtr(*p, Parent.Cast)(*p)  '' execute Cast(Parent, *p) through its vtable index
+#define RuntimeProcPtr(instance, procedure, signature...) _   '' pointer to procedure
+	__FB_IIF__(ProcPtr(procedure, Virtual signature) >= 0, _  '' (the most derived override if exists)
+			   CPtr(TypeOf(ProcPtr(procedure, signature)), _
+					CPtr(Any Ptr Ptr Ptr, @(instance)) _
+					[0][ProcPtr(procedure, Virtual signature)]), _
+			   ProcPtr(procedure, signature))
+
+'' Here, providing the procedure signature to the macro is useless
+'' (because there are no procedure overloads to solve in this case)
+RuntimeProcPtr(*p, Parent.VirtualTest)(*p)  '' execute (*p).VirtualTest() through its vtable index
+Print RuntimeProcPtr(*p, Parent.Cast)(*p)   '' execute Cast(Parent, *p) through its vtable index
+RuntimeProcPtr(*p, Parent.NormalTest)(*p)   '' execute (*p).NormalTest() through its compile address
 Print
 
 Delete p

doc/manual/cache/KeyPgScreencontrol.wakka

@@ -250,7 +250,7 @@ loop
 dim as string driver
 
 #ifdef __FB_WIN32__
-'' set graphics driver to GDI (Win32 only), before calling ScreenRes
+'' set graphics driver to GDI (Windows only), before calling ScreenRes
 screencontrol FB.SET_DRIVER_NAME, "GDI"
 #endif
 

doc/manual/cache/ProPgEmulateTlsTp.wakka

@@ -32,7 +32,7 @@ How **emulate** a kind of **TLS (Thread Local Storage)** and a kind of **TP (Thr
 		A single macro allows to define any TLS variable (except array) of any type.
 
 		- Code with preprocessor conditional directives depending on fbc version:
-				{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq12.bas"}}%%(freebasic)
+				{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetls1.bas"}}%%(freebasic)
 #include once "crt/string.bi"
 
 #if __FB_VERSION__ < "1.08"
@@ -303,7 +303,7 @@ end of threads
 							**""-""** A sequence of 9 ""'ThreadStart...ThreadWait'"" is also requested for this second user thread function, used like a thread function.
 
 						Full code with the ""'ThreadInitThenMultiStart'"" Type:
-							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq13.bas"}}%%(freebasic)
+							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetp1.bas"}}%%(freebasic)
 Type ThreadInitThenMultiStartData
 	Dim As Function(ByVal p As Any Ptr) As String _pThread
 	Dim As Any Ptr _p
@@ -557,7 +557,7 @@ Second user function executed like a thread function:
 							**""-""** A second sequence (b) of 3 ""'PoolingSubmit'"" is requested for the last three user thread functions, ended by a ""'PoolingWait'"" with a dynamic string array as argument (so, only the returns from the last three user thread functions will fill out in the dynamic string array).
 
 						Full code with the ""'ThreadPooling'"" Type:
-							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq13-2.bas"}}%%(freebasic)
+							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetp2.bas"}}%%(freebasic)
 #include once "crt/string.bi"
 
 Type ThreadPoolingData
@@ -829,7 +829,7 @@ Sleep
 
 				- Example:
 						Example of use of ""'ThreadDispatching'"" (whatever the allowed number of secondary threads, the submission sequence syntax is always the same):
-							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq13-3.bas"}}%%(freebasic)
+							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetp3.bas"}}%%(freebasic)
 #include once "crt/string.bi"
 
 Type ThreadPoolingData
@@ -1203,7 +1203,7 @@ Sleep
 							**""-""** For ""'ThreadDispatching'"": 32 sub-tasks are always used and the distribution of these sub-tasks over the available threads (max = 1/2/4/8/16/32) is automatic.
 
 						Full code with the ""'ThreadInitThenMultiStart'"", ""'ThreadPooling'"", and ""'ThreadDispatching'"" Types:
-							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq13-4.bas"}}%%(freebasic)
+							{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetp4.bas"}}%%(freebasic)
 Type ThreadInitThenMultiStartData
 	Dim As Function(ByVal p As Any Ptr) As String _pThread
 	Dim As Any Ptr _p
@@ -1768,7 +1768,7 @@ Sleep
 				The objective of thread pooling (""ThreadInitThenMultiStart"", ""ThreadPooling"", ""ThreadDispatching"" methods) is to pool threads in order to avoid the untimely creation or deletion of threads, and thus allow their reuse.
 
 				Test code to evaluate the different times wasted depending on the feature used:
-					{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq13-5.bas"}}%%(freebasic)
+					{{fbdoc item="filename" value="examples/manual/proguide/multithreading/emulatetp5.bas"}}%%(freebasic)
 Type ThreadInitThenMultiStart
 	Public:
 		Declare Constructor()

doc/manual/cache/ProPgMtCriticalSectionsFAQ.wakka

@@ -1582,7 +1582,7 @@ Sub threadUDT.condDestroy ()
 End Sub
 				%%
 		- From the example 2 on the ##[[ProPgMtCriticalSections|Critical Sections]]## page "Synchronous method example using a condwait then a condbroadcast (and a mutex) for all threads", now the user implementation is modified to be compatible with the base Class 'threadUDT':
-				{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq10-1.bas"}}%%(freebasic)
+				{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq11.bas"}}%%(freebasic)
 #include once "fbthread.bi"
 Type threadUDT Extends Object
 	Public:
@@ -1780,7 +1780,7 @@ Sleep
 	After a while of observation, one can find both small negative values and large positive values.
 
 	Interesting to see the min time, average time, and max time, between the executing start of thread body and the returning point of ""'ThreadCreate()'"":
-		{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq14.bas"}}%%(freebasic)
+		{{fbdoc item="filename" value="examples/manual/proguide/multithreading/criticalsectionfaq12.bas"}}%%(freebasic)
 Dim As Any Ptr ptid
 Dim As Double t0
 Dim As Any Ptr p0 = @t0

examples/manual/gfx/screencontrol2.bas

@@ -12,7 +12,7 @@
 Dim As String driver
 
 #ifdef __FB_WIN32__
-'' set graphics driver to GDI (Win32 only), before calling ScreenRes
+'' set graphics driver to GDI (Windows only), before calling ScreenRes
 ScreenControl FB.SET_DRIVER_NAME, "GDI"
 #endif
 

examples/manual/operator/procptr4.bas

@@ -6,41 +6,59 @@
 '' See Also: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgOpProcptr
 '' --------
 
-' Since fbc 1.10.0, ProcPtr allows to access the vtable index of a virtual/abstract member procedure/operator
+' Since fbc 1.10.0, ProcPtr also allows to access the vtable index of a virtual/abstract member procedure/operator
 
 Type Parent Extends Object
-	Declare Abstract Sub test()
+	Declare Abstract Sub VirtualTest()
 	Declare Virtual Operator Cast() As String
+	Declare Sub NormalTest()
 End Type
 
 Operator Parent.Cast() As String
 	Return "Parent.Cast() As String"
 End Operator
 
+Sub Parent.NormalTest()
+	Print "Parent.NormalTest()"
+End Sub
+
 Type Child Extends Parent
-	Declare Virtual Sub test()                 '' or Declare Sub test()
+	Declare Virtual Sub VirtualTest()          '' or Declare Sub test()
 	Declare Virtual Operator Cast() As String  '' or Declare Operator Cast() As String
+	Declare Sub NormalTest()
 End Type
 
-Sub Child.test()
-	Print "Child.test()"
+Sub Child.VirtualTest()
+	Print "Child.VirtualTest"
 End Sub
 
 Operator Child.Cast() As String
-	Return "Child.Ccast() As String"
+	Return "Child.Cast() As String"
 End Operator
 
+Sub Child.NormalTest()
+	Print "Child.NormalTest()"
+End Sub
+
 Dim As Parent Ptr p = New Child
-p->test()
+
+(*p).VirtualTest()      '' or p->VirtualTest()
 Print Cast(Parent, *p)  '' or Print *p
+(*p).NormalTest()       '' or p->NormalTest()
 Print
 
-#define VirtProcPtr(instance, procedure) CPtr(TypeOf(ProcPtr(procedure)), _       '' pointer to virtual procedure
-											CPtr(Any Ptr Ptr Ptr, @(instance)) _  '' (the most derived override that exists)
-											[0][ProcPtr(procedure, Virtual)])
+#define RuntimeProcPtr(instance, procedure, signature...) _   '' pointer to procedure
+	__FB_IIF__(ProcPtr(procedure, Virtual signature) >= 0, _  '' (the most derived override if exists)
+			   CPtr(TypeOf(ProcPtr(procedure, signature)), _
+					CPtr(Any Ptr Ptr Ptr, @(instance)) _
+					[0][ProcPtr(procedure, Virtual signature)]), _
+			   ProcPtr(procedure, signature))
 
-VirtProcPtr(*p, Parent.test)(*p)        '' execute p->test() through its vtable index
-Print VirtProcPtr(*p, Parent.Cast)(*p)  '' execute Cast(Parent, *p) through its vtable index
+'' Here, providing the procedure signature to the macro is useless
+'' (because there are no procedure overloads to solve in this case)
+RuntimeProcPtr(*p, Parent.VirtualTest)(*p)  '' execute (*p).VirtualTest() through its vtable index
+Print RuntimeProcPtr(*p, Parent.Cast)(*p)   '' execute Cast(Parent, *p) through its vtable index
+RuntimeProcPtr(*p, Parent.NormalTest)(*p)   '' execute (*p).NormalTest() through its compile address
 Print
 
 Delete p