GFA-BASIC 32 for Windows

How a GLL Dialog # is created

2012-02-05T20:47:00.001+01:00

The Dialog command used in a GLL editor extension is quite different than the Dialog in a normal GB32 application. How is that possible?

When one or more GLLs is loaded in memory, the IDE assigns the compiled GLL an array with pointers to the GB32 library functions in the runtime DLL (or Ocx). This is the same array with pointers each application gets when it is loaded. This way a call to a library function like Left$(), Dialog, or OpenW, etc, will reference the appropriate function in the runtime. When the GLL is loaded some of these pointers are replaced by addresses of functions inside the IDE executable. This way when the GLL invokes a dialog related function it will call the function inside the IDE, rather than in the runtime. All the dialog box related functions and commands are replaced. Examples are the Control command and the names of standard and common controls. You'll find an overview of the valid GB32 dialog box related statements and functions in the help file.

The GB32 dialog box related statements and functions are GfaBasic for Windows 16-bit-compatible. However, the window styles specified in the Dialog # command may come as a surprise. When you omit the style GB32 uses a default window style. GB32 processes as follows:

' Create a dialog box
Local Long dwStyle = 0
Dialog # 1, 200, 200, 536, 400, "" , dwStyle
EndDialog

'
' How GB32 sets the Dialog window styles.
'
If (dwStyle %& DS_MODALFRAME) Then
  Ex_Style = WS_EX_DLGMODALFRAME | WS_EX_CLIENTEDGE

Else If dwStyle == 0                  ' Default Style?
  dwStyle = WS_POPUP | WS_DLGFRAME | WS_BORDER
  If Len(szTitle) == 0                ' No Title?
    dwStyle  = WS_POPUP | DS_MODALFRAME
    Ex_Style = WS_EX_DLGMODALFRAME
  EndIf
EndIf
'
dwStyle  |= DS_SYSMODAL       ' Top Most

The system creates the window (dialog box) with the WS_EX_TOPMOST style using CreateWindowEx(). The dialog has no owner or parent. It is modeless because it exist parallel to the Gfa_hWnd IDE window.
The WS_EX_TOPMOST style does not prevent the user from accessing other windows on the desktop.
This gives you the tools puzzle the appearance of GLL dialog box and might explain its unexpected visual style.

Gfa_Setting() returns extra #0

2012-01-29T10:18:00.001+01:00

Gfa_Setting is available as a statement and as a function. They are used as follows:

' Set/Create a subkey
Gfa_Setting("MySubKey") = mysetting$
' Get subkey value ($)
mysetting$ = Gfa_Setting("MySubKey")
' Delete a subkey
Gfa_Setting("MySubKey") = ""

The Gfa_Setting(subkey$) reads a value from the subkey under HKEY_CURRENT_USER\Software\GFA\Basic using the RegQueryValueEx() API function that retrieves the data for a specified value name associated with an open registry key. The advantage of using this API is that it doesn't require a data type. Even better, the function returns a code indicating the type of data stored in the specified value. The possible type codes are:

Const REG_NONE  = 0
Const REG_SZ  = 1
Const REG_EXPAND_SZ  = 2
Const REG_BINARY  = 3
Const REG_DWORD  = 4
Const REG_DWORD_LITTLE_ENDIAN  = 4
Const REG_DWORD_BIG_ENDIAN  = 5
Const REG_LINK  = 6
Const REG_MULTI_SZ  = 7
etc..

After invoking RegQueryValueEx GB32 checks the value in the type parameter and than decides how to copy the data to the GB32 variable used in the var$ = Gfa_Setting(subkey$) code. When the type value returned is REG_SZ or REG_EXPAND_SZ or REG_BINARY then GB32 uses the StrPeek(addr, size) function to create and copy the data to the string. The size of the data is also returned by RegQueryValueEx. Simple enough. But there is a catch that is overlooked:

"If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then the data will also include the size of the terminating null character or characters."

GB32 uses the size value to invoke StrPeek and stores the terminating #0 character inside the string and sets the length of the string to the size of data + 1 for the #0 character. GB32 uses the same function for Gfa_BinSetting() and does not care for the value of the size.

Now, when you apply a string concatenation (str & str2) the second string doesn't seem to be appended to the first string. The including #0 character in the last position of the string makes the use of string functions awkward. When you pass that string to a function that expects a C-string the string data is read to the first #0 character. Internally, and externally on the API level, many functions expect a C-string and stop processing the string at first occurrence of a #0 character.

For now, you best use ZTrim() on the return value of Gfa_Setting(). It seems not to predict how many #0 characters will be included. See underlined words in the quotation.

' Get subkey string value
mysetting$ = ZTrim(Gfa_Setting("MySubKey"))

Gfa_Line doesn't always redraw the caret

2012-01-20T12:10:00.001+01:00

The GFA-BASIC implementation of the editor-extension contains a large set of Gfa_* functions and commands. However, in contrast with the term 'editor extension', the Gfa_* statements are not restricted to the (text) editor only. The GFA-BASIC IDE application itself is divided into several entities such as an application part, a form-editor, a compiler, and a text-editor. Only a part of the Gfa_ statements apply to the text-editor only, and the most important terms in this respect are 'text-selection' and 'insertion point'.

The active point
The text-selection represents a selection in the code text in the editor window. Note that a selection can be a single point (the insertion point) or a contiguous range of text. Using Gfa_ commands you can move the insertion point, control which text is selected, and modify the contents of the selection. When the text-selection is restricted to a single point, Gfa_Line and Gfa_Col return its position. Also, since there is no selection, Gfa_Line equals Gfa_SelLine and Gfa_Col equals Gfa_SelCol.

Whether or not the text is selected, the Gfa_Line and Gfa_Col always indicate the active point. This is the point where all other text actions are performed. When a range of text is selected the insertion point can be located at the beginning or at the end of the selection.

Command	Description
Gfa_Line	Gets/sets the line where the insertion point is.
Gfa_Col	Gets/sets the column where the insertion point is.
Gfa_SelLine	Gets/sets the line at the bottom of a selection. The bottom line is not necessarily at the active end of the selection.
Gfa_SelCol	Gets/sets the column at the bottom of a selection. The bottom line is not necessarily at the active end of the selection.

Moving the caret
The insertion point is represented by a caret, is a blinking line, block, or bitmap in the client area of a window. The caret typically indicates the place at which text (or graphics) will be inserted. The caret is a system resource and controlled by invoking Windows system API calls such as ShowCaret() and SetCaretPosition(). Each time the caret is moved SetCaretPosition() is invoked.
Programmatically, you move the caret using one of the following Gfa_ commands:

Command	Key Press
Gfa_Left [count ]	LEFT ARROW
Gfa_Right [count]	RIGHT ARROW
Gfa_Down [count]	DOWN ARROW
Gfa_Up [count]	UP ARROW
Gfa_PageDown	PAGE DOWN
Gfa_PageUp	PAGE UP

count is optional. A Long that specifies the number of times you want to repeat this action. The default is one.

When executing one of these commands (or pressing the key(s)) the current selection is canceled before the action is performed.
These are relative movements. They move the caret relative to the current active insertion point represented by Gfa_Col and Gfa_Line.
Many key press actions are not represented by a Gfa_ command. For instance: word-left, word-right; end-of-line, start-of-line; etc.

So, how do you move the caret to an absolute position, rather than to a relative one? Within a text line the Gfa_Col = newcolumn command will do the trick. It cancels any selection and updates the caret position. By assigning 0 to Gfa_Col the caret moves to the start-of-the-line and by setting it to some large number (_maxInt) is moves to the end-of-the-line. Consequently, you expect Gfa_Line to do the same for lines. Well it does modify the current line, but it sometimes 'forget" to update the caret visually. Meaning, it forgets to put the caret into its new position.

Gfa_Line = doesn't redraw caret
The Gfa_Line = command differs in two aspects from all other commands. First it doesn't cancel a selection, and, secondly, it doesn't always redraw the caret in it's new position. It does however change the current line used for text operations, which is important because some text operations are line oriented. So, without displaying the caret at the new position (combined with a possible scrolling) the current active line can be changed to perform actions on the text line (Gfa_Update, Gfa_Text = , delete and insert lines, setting a bookmark, clipboard actions, etc). The problem is that the editor extension implementation lacks a command to update the caret explicitly.

Workaround to redraw caret
To explicitly make the caret visible after invoking Gfa_Line = we must take into account that as portion of the text maybe selected. So, first we must cancel any selection and after invoking Gfa_Line = we must redraw the caret ourselves.

Global Gfa_SetCaret As Pointer Byte
Pointer(Gfa_SetCaret)       = $4DC41C
Global Const Ed_SetCaretPos = $409B99



' Cancel selection (if any)
Gfa_Col  = 0
' Set/Goto new line
Gfa_Line = iGotoLine
' Set global flag (when in OnWMCommand)
Gfa_SetCaret = 1
' Or call directly
~StdCall(Ed_SetCaretPos)()

Most (if not all) IDE commands are processed in the IDE's OnWMCommand() function. This is a central routine to execute all accelerator key commands, menu commands, and the GLL's key and menu events. Besides this, it adds the commands to the UNDO-buffer and stores them in a keyboard macro when Gfa_IsRecording = True. At the end of IDE's OnWMCommand() function the global variable Gfa_IsCaret is checked to see if any of the executed commands did set this flag (to have the caret redrawn). If so, before returning from OnWMCommand() the IDE's Ed_SetCaretPos() function is invoked to redraw the caret and Gfa_SetCaret is cleared.

Now you have some background knowledge of Gfa_Line you have the tools to properly redraw the caret.

GFA-BASIC 16 Bit Revival

2011-11-14T12:17:00.001+01:00

The Frenchman Michel Goux has assembled all tools for a proper installation of GFA-BASIC for Windows 16 Bit (also known as Windows 3.1). All tools like IDE, Compiler, Linker, ExtTool, etc are to be downloaded into one new package. The package also includes tips for running the 16-bits version on more recent OS's like Vista-32 and Windows 7-32.

Unfortunately, it will not run on 64-bit systems? Maybe some have a solution for that?

Go to the Michel's GfaWin16 download page.

You can also check-out my GFA-BASIC 16 page for downloading additional stuff.

Apply XP Visual Styles

2011-11-08T11:25:00.001+01:00

Running GFA-BASIC 32 under XP or better (Vista/7) it applies the Windows XP Visual Styles. The controls are drawn using a new look using a newer common control library. The IDE uses the newer look because of the presence of manifest file in the same directory as the GfaWin32.exe. When you create an EXE for your own GFA-BASIC application you must not forget to include a manifest file using the same name as your application.

Go to the CodeProject site for a brief introduction on Applying Windows XP Visual Styles.

For an implementation of a GFA-BASIC 32 project go to Peter Heinzig site for an example http://www.peterheinzig.de

Dim ... As New Interface?

2011-11-02T11:08:00.001+01:00

What does New mean when used in a declaration statement? Why is New limited to only 8 so called OCX types? What are OCX types anyway? Confused? Let us continue the story on COM.

OCX Objects
By now you know that in GFA-BASIC 32 OCX windows are, in fact, normal windows and controls wrapped up in a COM Object. For instance, the very familiar OpenW # command still creates an overlapped application window, but it now also creates a COM wrapper of data type Form. Not only creates OpenW a window using the CreateWindowEx() API, but also allocates an additional block of memory (using malloc) to store all COM related information for the Form object type.

A GFA-BASIC OCX object is a window wrapped in a COM object. An OCX object requires a window handle.

Information about the OCX
An OCX object is also called an ActiveX control (hence the window handle). GFA-BASIC OCX objects must behave as proper ActiveX objects as described in the OLE/COM documentation. (Actually, OLE is an old name. On the way it changed to COM.)
To use/control a COM object it must somewhere describe (publish) its functions, called properties and methods. This is done by including a type library with a COM object. The type library also specifies whether the COM object supports the creation of an instance of that object. This literally means that the COM object provides a class (function) doing a malloc() to allocate the memory to store the object.

A type library specifies the properties and methods of a COM object (interface), and whether it can be created on behalf of the client (coclass).

Declaring a COM Object
If you have ever used OleView.exe to examine GFA-BASIC's COM objects, you may have noticed the term interface. The interface specifies the name of the COM type and the functions used to access it. The interface name always starts with a capital I - like IForm, ICollection, etc. When used in code the capital I is lost (VB convention, duplicated by GB32).

All the interfaces defined in the type library from the GFA-BASIC Ocx runtime DLL are added to the GFA-BASIC 32 internal list of data types. (This list is accessible through the Gfa_Types collection.) The list of data types contains all primary types like Bool, Byte, Card, Int32, Long, Currency, String, etc. All names stored in the type-list can be used in a declaration command like Dim, Global, and Local.

There is small problem though. GFA-BASIC 32 doesn't add the COM types by loading them from the type library. The addition of COM types like Collection, DisAsm, TextBox, etc. is hard-coded into the IDE code. Unfortunately! Otherwise we could have easily added third-party COM references to our applications.

To understand how GFA-BASIC handles a declared COM data type we can compare a COM object type to a String data type. For instance

Dim MyName As String
Dim frm As Form

These declarations don't do much. MyName and frm are variable-names and both are an alias for a 4-byte memory location. Initially, the value stored at the addresses is zero (pointer is Null), meaning no additional memory has been allocated for these variables. The pointers remain Null until something is assigned to the variables. Because MyName is of type String, GFA-BASIC knows how to do that and how to interpret the pointer at the location MyName.

The same is true for COM data types. Declaring a COM data type does not create the memory for it. The frm variable references some memory-address, but it does not actually create a window on the screen. First the window must be created and then the variable can be assigned an object of type Form. For COM objects a special command is invented to assign one COM object to another Set:

OpenW 1
Set frm = Win_1

Most GFA-BASIC 32 COM objects are created implicitly. OpenW creates a Form object, OCX TextBox creates a TextBox object, and so on. In addition, OCX controls that require multiple subitems create collections. A ToolBar OCX creates a Buttons collection of Button items.
For implicitly created objects GFA-BASIC 32 is responsible for memory allocation, initialization, and releasing memory.

Some COM types are created explicitly when some data is loaded. The LoadCursor() function creates a MouseCursor object and LoadPicture() creates a Picture object. These functions can be seen as 'a kind of New'.

The New keyword
The New keyword is used with some COM types that are available at your request. These types are independent of any OCX type. The New keyword allows you to create an instance of the object while declaring it. In GFA-BASIC 32 there are only 8 of these COM types allowed.

Dim f   As New Font       ' IFont2
Dim sf  As New StdFont    ' IStdFont
Dim p   As New Picture    ' IPicture2
Dim sp  As New StdPicture ' IStdPicture
Dim cd  As New CommDlg    
Dim col As New Collection
Dim dis As New DisAsm
Dim iml As New ImageList

Font (IFont2) and Picture (IPicture2) are GFA-BASIC implementations of the standard COM types.
StdFont and StdPicture are the types from the standard OLE libraries. Font and StdFont are 'compatible'. A variable of type Font can be set to an instance of StdFont and vice versa. The same is true for Picture and StdPicture.
The CommDlg and ImageList objects can be created using the OCX command as well.
Once the object created with New goes out of scope the object is automatically released.
Objects can be released explicitly by setting the variable to Nothing.

Other objects are single-instance objects created at runtime. GFA-BASIC 32 prohibits the creation of additional, new objects of these types. There is only one instance of App, Screen, Printer, ClipBoard, Code4, Debug, and Err. The single-instance objects are released when the program is terminated.

Cleanup after an exception

2011-10-23T12:13:00.001+02:00

In the previous post Don't use END to terminate your application I discussed why End messes up the memory available to an application. The same is true for Assert and Stop (when you use to terminate the application).

Main exception handler
These commands raise an exception caught by the nearest exception handler. This might be a custom Try/Catch handler in your program, but most often it passed on to the applications main exception handler. The main part of a GB32 application is surrounded with a GB32 generated application-exception-handler that releases file handles and memory associated with GB32 data types. The OCX forms/controls are not part of the cleaning process. To properly release all COM object memory all forms have to be closed by an internal function Destroy_Form(). The forms in turn are responsible for releasing the OCX objects of the child windows (controls).

Custom handler
When you use a custom structured exception handling (Try/Catch) in your application the exceptions might be caught by your application's defined custom handler. Now the exception is not passed on to the main application-handler and no memory and file handles are released. When you are put in this situation, you can select the clean-up command from the IDE's menu to close all forms and file handles.

Cleanup opened Forms and files
GB32 includes a library function that can cleanup non-closed forms and files after an application terminates abruptly. The DLL-function is located in the runtime and is exported by ordinal #49. The function is automatically invoked when you RUN a program inside the IDE. But you can also invoke it by selecting 'Clean up' (shortcut Ctrl-L) from the IDE's menubar. The menuitem executes the Gfa_CleanUp command that invokes the DLL cleanup function.

Why would you use Gfa_CleanUp when the same function is executed at the next RUN of your code? Well, programs that are terminated improperly (END, ASSERT, or any exception the program causes) leave with invalid memory-pointers and Gfa_CleanUp might fail (mostly likely it will).

Gfa_CleanUp executes within a exception handler itself and it first calls DLL function #49 to close the forms. If it returns properly it calls exported function #119 which cleans the file handlers. In short, this is what Gfa_CleanUp looks like:

Try
G49_CleanUpForms()
G119_CleanUpFiles()
Catch
EndCatch

When the G49_CleanUpForms() DLL function causes an exception the G119_CleanUpFiles() is never executed!

The G49_CleanUpForms() simply enumerates over the Forms collection to call each Destroy_Form() internal function. This function is responsible for deleting form-specific COM objects for Fonts, MouseCursors, Pictures, Icons, AutoRedraw bitmaps, Menus, controls, graphic settings, end other related COM objects. This is a very large function responsible for properly clearing (in the right order) all created COM objects. When something didn't work correctly in your application and it was terminated in an unstable state, it is most likely this function might fail. This might leave behind all kinds of allocated COM memory. In addition, the function might have generated an exception, most likely of an invalid memory pointer, and from the pseudo code above you then see that the file handles aren't released at all.

In conclusion,

When you set up a new application use a proper message loop and try to created one main-form that owns other forms (set the Form.Owned property for the second and later forms in the Properties window). Closing the main-form will close all other forms.
Don't use END and be careful with ASSERT. When an application terminates improperly try using invoke Gfa_CleanUp.
Fix an exception error and make sure it won't happen again. Then restart the IDE to get rid of memory left-overs.

Don't use END to terminate your application

2011-10-16T13:33:00.001+02:00

Using the End statement is like waking up from a nightmare. After multiple 'runs' in the IDE the GFA-BASIC 32 IDE might stop working at all and crashes eventually. End does not behave as it did in previous versions of GFA-BASIC where it was safe to use it as the application termination command. In GB32 you should never use End to terminate a program. Here is why.

End is defined as to terminate the execution of an application immediately. End is never required by itself but may be placed anywhere in a procedure to end code execution, close files opened with the Open statement and to clear variables.

The End statement stops code execution abruptly, without invoking the any window events, or any other code. Code you have placed in the form_Destroy, form_Close, etc, is not executed. GB32 data types referencing allocated memory at runtime (strings, arrays, hash tables) are properly destroyed, and files opened using the Open statement are closed. Object references held by other programs are invalidated.

The End statement provides a way to force your program to halt. For normal termination of a GB32 program, you should close all forms. Then when you use the 'Do : Sleep : Until Me Is Nothing' loop your program closes as soon as there are no more forms open. This is the only proper way to run a program!

Note The same is true for Quit, Assert, and Stop. These commands do not terminate your application properly.

It is an exception dude
For the curious. When GB32 encounters the End, Assert, and Stop commands GB32 it inserts code that raises an exception event: GB32 inserts a call to the RaiseException() API. An “exception” is an event that is unexpected or disrupts the ability of the process to proceed normally. However, GB32 supports structured exception handling (Try/Catch) the exception is caught by the nearest exception handler. In most cases, and certainly when End is used to terminate an application, the exception is caught by GB32's main-program exception handler. This handler is implicitly inserted around the code in the main program part of a GB32 program. Each unhandled exception is eventually handled by this main exception handler. The handler does nothing more than clearing variables and closing file handles.

So, when GB32 suddenly stops working, make sure your code let the OCX forms and controls properly close their windows in a natural order.

Also Known As bugs
NOTE – Don't blame GB32 too soon! Their are little or no bugs in the memory handling of GB32. Without pointing any fingers..., it turns out that most GB32 blamers are frustrated programmers that can't get their program(s) to work. Often the program structure is wrong or the programmer is under-qualified. This then leads to mysterious mistakes, AKA GB32 bugs.

CreateObject peculiarities

2011-09-05T11:32:00.001+02:00

Why CreateObject isn't fully compatible to VB(Script).

Introduction
The GFA-BASIC 32 function CreateObject() creates and then references a COM automation object. Usually the function is used to control a target application (or documents or other objects supported by the target application). Controlling a target application through COM (or OLE) is called OLE Automation.

Understanding OLE Automation
OLE Automation is an OLE service for integrating applications. It enables an application to expose its functionality (MS Word), or to control the functionality of other applications on the same computer or across networks. As a result, applications can be automated and integrated with programming code, creating virtually endless possibilities. OLE Automation is the umbrella term for the process by which an OLE Automation controller sends instructions to an OLE Automation server (using the functionality exposed by the OLE Automation server), where they are run.

CreateObject returns a reference to an object determined by the class argument.

Syntax: Set object = CreateObject(class)

Depending on class, the reference may be to an existing object or to a newly created object. The object reference returned by CreateObject is (usually) assigned to an object variable of type Object. Assigning a COM object to a variable differs from assigning a value or variable to another variable. It always requires the Set statement (as opposed to the Let statement that is implicitly used by other assignments).

Note - Using CreateObject (or GetObject) to set the Object-variable to the target application, or some object that the target application supports, establishes a reference to the target application's Application object. Then the object variable in the sourcecode can use the methods and properties of the corresponding object in the target application.

The ProgID of an automation object
To create an automation object the class argument of CreateObject(class) can be a string of the form "appName.objectType". A string using this format is called a ProgID.
A ProgID is a string that gets converted to a CLSID (a 128-bits GUID value) by looking up the string in the register. Note that the automation object can only be found when it has registered itself using the same string format "appName.objectType". This happen,s for instance, with MS Excel which registers itself as "Excel.Application". And Internet Explorer as "InternetExplorer.Application". These applications can be referenced through automation as follows:

Dim obj As Object
Set obj = CreateObject("Excel.Application")

The class argument
In GFA-BASIC 32 the class argument may also specify CLSID either as a string (1) or as GUID constant (2). For instance:

Dim obj As Object
Set obj = CreateObject("7b55b57b-cd72-449d-82eb-a02e0964e3eb")

GUID gd = 7b55b57b-cd72-449d-82eb-a02e0964e3eb
Set obj = CreateObject(gd)

Remarkable features of GFA-BASIC's CreateObject() are:

The class$ argument can specify a GUID value as a string.
The parameter can specify the address of GUID user-defined type. (The GFA-BASIC statement GUID name = xxx..-..-.._..-...x defines a constant (Long) as the address to a GUID value.
The syntax does not support the second optional parameter server as is described in Help documentation.
The language locale of the target application can be set prior to invoking CreateObject() using Mode(Lang) = .
The CreateObject() function is not 100% VB(Script) compatible.

CreateObject 's compatibility
In COM terms CreateObject() connects to a coclass at run time using the IDispatch interface (late binding). The Object variable type performs property and method operations using the IDispatch interface functions. Once you’ve created a new object and returned a reference to it, you can work with the object in GFA-BASIC in the same way you would work with any other object. That is, you can set and retrieve the object’s properties and apply its methods. To be an automation object the object must support IUnknown and IDispatch. All COM objects support IUnknown, because that defines them as a COM object. See this post on COM interfaces.
The IDispatch interface defines late binding and allows a client to call the methods and properties on the server. Consequently, without supporting an IDispatch interface a server cannot be called an automation controller. GFA-BASIC 32 consequently asks the automation object for an IDispatch interface and only connects to the coclass when it acknowledges that it supports an IDispatch interface. Otherwise it generates a runtime error.

VB(Script) are wrong
However VB and VBScript implement CreateObject differently, more flexible maybe, but essentially wrong. At the heart of creating an object is the OLE function CoCreateInstance(). It takes a pointer to the interface the program wants to use to communicate with the object. Since 'OLE automation' is required, it seems logical to pass the GUID for the IDispatch interface (as GFA-BASIC 32 does). But VB(Script) doesn't. The VB-CreateObject passes the GUID for IUnknown which every COM object supports, because IUnknown is what an object makes a COM object in the first place! So in VB CreateObject always works, even when it shouldn't. But the object reference returned by VB's CreateObject is not guaranteed to support IDispatch.

Porting VB to GB
This causes trouble when porting a VB program to GB. Implicitly CreateObject calls the object's QueryInterface(), asking it if it supports IDispatch. A correct behavior for QueryInterface(0 would be to reply for each interface it supports. Badly written OLE automation objects sometimes forget to reply for all interfaces it supports (especially IDispatch). One of them is Microsoft's type-library-reader-tool "TLI.TypeLibInfo". CreateObject fails with GB where VB does return a reference:

Set TLInfo = CreateObject("TLI.TypeLibInfo")

When GB's CreateObject doesn't work where VB(Script) works, don't blame GFA-BASIC 32, but the COM programmer instead. BTW in these cases you must use the CoCreateInstance() API.

Update Runtime (Ocx) Build 1171 (reSub fix)

2011-08-09T11:42:00.001+02:00

Yet another update for the runtime (DLL or Ocx) of GFA-BASIC 32. The Build 1171 differs from Build 1170 by fixing the reSub command's max argument. This not only allows you to set a maximum to the number of replacements, but it also fixes the overall functionality of reSub().

You'll find your download on the Download page accessible at the top of this site.

For an explanation on the purpose of the runtime see Update Runtime Build 1170.

COM (OOP) in GB32 - IUnknown (1)

2011-07-15T09:57:00.002+02:00

In this part I'll show you the layout of a COM class as it could be implemented in GFA-BASIC 32. Note that we restrict ourselves to a minimalist COM object that supports the IUnknown interface only. We will not yet create properties and methods.
The GFA-BASIC 32 approach is loosely based on the article series COM in plain C by Jeff Glatt, specifically Part 1 and Part 2. However, in the first step we are not going to use type libraries, we are not going to store the COM object in a DLL, and we are not going to define another COM object that creates the one we define. COM is merely a binary standard; it dictates how to layout an array of function pointers and where to put the address of this array (of function pointers). It also dictates how to add reference counting. To comply to this standard a COM object must at least contain three pointers to pre-defined functions, also known as the IUnknown interface. In GFA-BASIC 32 this could look like this:

// IUnknownBlog.g32 17.07.2011
Debug.Show

// Our COM object: an implementation of IUnknown
GUID IID_IUnknownImpl = 9578fdab-97cb-4322-99e4-699abd26be1d
Type IUnknownImpl
  lpVtbl As Pointer IUnknownImplVtbl
  RefCount As Int
EndType

// VTABLE (an array of function pointers)
Type IUnknownImplVtbl
  QueryInterface As Long
  AddRef As Long
  Release As Long
EndType
Static IUnknownImplVtbl As IUnknownImplVtbl
With IUnknownImplVtbl
  .QueryInterface = ProcAddr(IUnknownImplVtbl_QueryInterface)
  .AddRef = ProcAddr(IUnknownImplVtbl_AddRef)
  .Release = ProcAddr(IUnknownImplVtbl_Release)
EndWith

// First create a heap allocated instance
// of our implementation of IUnknownImpl
Dim pIUnk As Pointer IUnknownImpl
Pointer pIUnk        = mAlloc(SizeOf(IUnknownImpl))
Pointer pIUnk.lpVtbl = *IUnknownImplVtbl
pIUnk.RefCount = 1

Dim obIUnk As Object
{V:obIUnk} = V:pIUnk
Trace obIUnk


Dim o As Object // assign to other
Set o = obIUnk  // AddRef() call
// two calls to Release
/*** END ***/

GUID IID_IUnknown      = 00000000-0000-0000-c000-000000000046
Global Const E_NOTIMPL = 0x80004001
Global Const E_NOINTERFACE = 0x80004002
Declare Function IsEqualGUID Lib "ole32" (ByVal prguid1 As Long, ByVal prguid2 As Long) As Bool

Function IUnknownImplVtbl_QueryInterface( _
  ByRef this As IUnknownImpl, riid%, ppv%) As Long Naked
  Trace Hex(*this)
  {ppv} = Null
  If IsEqualGUID(riid, IID_IUnknownImpl) || _
    IsEqualGUID(riid, IID_IUnknown)
    {ppv} = *this
    IUnknownImplVtbl_AddRef(this)
    Return S_OK
  EndIf
  Return E_NOINTERFACE
EndFunc

Function IUnknownImplVtbl_AddRef(ByRef this As IUnknownImpl) As Long Naked
  Trace Hex(*this)
  this.RefCount++
  Return this.RefCount
EndFunc

Function IUnknownImplVtbl_Release(ByRef this As IUnknownImpl) As Long Naked
  Trace Hex(*this)
  this.RefCount--
  If this.RefCount == 0 Then ~mFree(*this)
  Return this.RefCount
EndFunc

Copy it to a new GFA-BASIC 32 application and save as IUnknownBlog.g32. Try to run it; it should compile and run flawlessly. Our first minimalist COM object/class has been defined and is up and running. Of course it doesn't do anything, but the we have an object that integrates with GFA-BASIC 32 and fully complies to the COM binary standard.
Assign to Object
Let us take a brief look at the code. Since this project isn't meant for the beginner, I'll walk you through it in big steps.
The Object data type holds a pointer to a piece of memory of at least 4 (lpVtbl) bytes. Mostly it contains another integer for a reference count. In GFA-BASIC 32 the Ocx variables always define their count in the second slot, we will use that as well.
To put a memory address in an Object variable we usually use Set obj2 = obj2. GFA-BASIC 32 checks for two proper COM object types at compile-time. Since we have mAlloc-ed address only this syntax wouldn't work. We must write it to Object directly. For the same reason we set the RefCount to 1 by hand.
The array of functions (VTABLE) is stored in a Type and shared with all instances of our custom COM object. Therefor a static (global) variable is used and initialized once. Each new COM object should hold the vtable-address in its lpVtbl member.
_QueryInterface, _AddRef, and _Release
The application COM functions _QueryInterface, _AddRef, and _Release are never called directly, but always by GFA or another COM object. They clutter up our application code and are in fact just boiler plate code. We must do something about that, for instance put them in a $Library. Also note the Naked attribute. These functions are never executed in the context of the application and need no TRACE code and Try/Catch-exception handler. They should be as naked as possible to gain the best performance.
The Trace *this commands in the code are to verify the address passed. Also note the type of the this pointer. COM passes the address of the COM object by reference and by adding the correct type into the function declaration we can access its members directly. All other parameters are simple placeholders for addresses we don't use or pass on.
In the next part we will implement an IDispatch object and try to integrate the COM code more into GFA-BASIC 32.

Passing a Hash to a procedure (III)–Workaround

2011-05-24T08:36:00.002+02:00

This part three in a series about the GFA-BASIC 32 Hash data type. In this part I discuss a workaround to use Hash procedure parameters and some peculiarities of the hash data type. However, you might like to read the previous posts first.

The workaround
A compiler bug blocks the the Hash Xxx commands for a Hash data type passed by-reference. On the other hand, the hash [ ] - operator syntax works well. The Hash Xxx commands work correctly for a local Hash data type, the one that is not passed as an argument to the procedure. The logical conclusion is to declare and use a temporary local Hash of the same data type and then somehow 'assign the hash parameter to the local hash'.
GFA-BASIC 32 has a two constructions to do just that:

Declaring a variable p As Pointer To data-type and than use Pointer(p) = address command to assign the pointer (<=> variable) an address.
Swapping the descriptors of the Hash variables: Swap hs1, hs2.

We can skip the first option. It should work but it doesn't, the compiler refuses the statement:

Dim hs As Pointer Hash Int

The swap method should work as well, but again it doesn't. The compiler doesn't know what to do with Swapping two Hash variables. However there is light at the end of the tunnel, Swap works for all other GFA-BASIC 32 data types including the UDT (Type). And that's the one we are going to use to Swap the hash variables, hence the procedure SwapHash().

Local hsInt As Hash Int
hashtest(HB[])

Proc hashtest(ByRef HS As Hash Int)
  Dim ths As Hash Int   ' temporary Hash
  SwapHash( *HS, *ths ) ' swap descriptors

  ' Now ONLY use ths[]
  Hash Add ths["dd"], 7
  ths ["aa"] = 8
  ' ...

  SwapHash( *HS, *ths ) ' swap back
EndProc

Proc SwapHash(ptrHash1%, ptrHash2%) Naked
  Local hsdesc1 As Pointer HashDesc
  Pointer(hsdesc1) = ptrHash1
  Local hsdesc2 As Pointer HashDesc
  Pointer(hsdesc2) = ptrHash2
  ' Make sure the types are the same:
  Assert hsdesc1.pType == hsdesc2.pType _
    ' SwapHash() - Hash type mismatch

  Swap hsdesc1, hsdesc2

  Type HashDesc         ' The Hash Descriptor
    pHashData As Long   ' pointer to memory
    pType As Long       ' Hash data type
  EndType
EndProc

Passing a Hash to a subroutine (II) - The Descriptor

2011-05-19T10:28:00.004+02:00

In the previous post we discussed the GFA-BASIC 32 compiler bug when a Hash variable is passed to a subroutine. The compiler produces incorrect code for the Hash Xxx commands, but it works well in case hash-operators are used.
The situation is like this:

Sub q(hs As Hash String)
  ' Errorneous:
  Hash Add hs["mykey"], "Entry1"
  Hash Add hs[2], "Entry2"
  ' OK:
  hs[3] = "Entry3"
  Print hs[%]
EndSub

Note that the Hash variable hs is passed by-reference (implicitly due to the use of the keyword Sub).

Hash descriptor
A Hash variable is actually a 8-byte structure (user-defined type) containing two LONG integers. The Hash variable references the address of this hash-type, called the descriptor. The Hash-descriptor is defined as follows:

Type HashDesc
  pHashData As Long
  pType As Long
EndType

After declaring a hash variable (Dim hs As Hash type) the first long integer of the descriptor is Null indicating that the hash didn't allocate any memory. The second long contains a value indicating the GFA-BASIC 32 primary data type used to store values in the hash table. The data type could be Int, Byte, String, Variant, etc. Every GFA-BASIC 32 data type can be used, with the exception of UDT types. As an example the next code declares a Hash to store (long) Integer values and displays the descriptor:

Local HB As Hash Int
Local hs_desc As Pointer To HashDesc
Pointer(hs_desc) = *HB
Debug "HASH DESCRIPTOR"
Trace Hex(*hs_desc)
Trace Hex(hs_desc.pHashData)    ' = 0
Trace Hex(hs_desc.pType)        ' = $4018

The variable HB references the starting address of the 8-byte descriptor. As with any GFA-BASIC 32 variable that uses a descriptor, the address can be obtained using ArrPtr(HB) or *HB. Using the preceding code you can inspect the descriptor.

Hash MUST be declared as ByRef
When a hash variable is passed to a subroutine, its descriptor address is always passed by reference (whether or not ByRef or ByVal is used in the procedure header). BUT, the Hash parameter MUST be ByRef, otherwise the code generated for the procedure will use a wrong address. A ByVal Hash parameter sets the compiler in error mode without returning to the editor. As a consequence all code following might (will actually) be compiled wrongly.
When the Hash parameter is passed correctly by-reference the compiler still generates incorrect code for the Hash Xxx commands, like Hash Add, Hash Remove,...
The advise remains the same, don't pass Hash tables around, but use them as global variables only.

Hash passing to a subroutine (I) - The bug

2011-05-18T09:54:00.002+02:00

As mentioned in the (English) help file the handling of a Hash type argument is erroneous. The compiler produces incorrect code when the local Hash parameter is used in Hash commands like Hash Add, Hash Remove, etc. As far as I know all Hash Xxx commands suffer from the compiler bug. In contradiction with this behavior is the handling of the Hash–operator code. When a Hash data type is passed to a subroutine the compiler produces correct code for all [ ] hash-operator code. The following code illustrates the situation:

Sub q(hs As Hash String)
  ' Errorneous:
  Hash Add hs["mykey"], "Entry1"
  Hash Add hs[2], "Entry2"
  ' OK:
  hs[3] = "Entry3"
  Print hs[%]
EndSub

What is happening?
Due to the implicit Sub by-reference passing the compiler puts the address of the Hash argument on the stack when invoking q( Hs[] ). This is the first step performed by the compiler when a call to q() must be produced and it turns out to be ok. The second step performed by the compiler is when the subroutine q() is compiled. Due to the by-ref passing the compiler must set the local hs variable to the address put on the stack by the code that invoked the call. That way the local variable hs points to the same data as the hash passed to q().
However, somehow the compiler messes up with the Hash Xxx commands. When inspecting the assembly code for q() it can be seen that for the hash-operator instructions the correct Hash address is passed to the runtime library functions. Also, it is clear that the compiler passes the incorrect address in case the Hash Xxx commands are used.

What is to be done?
At this moment this bug cannot be fixed, so we either need a workaround or we avoid the use of Hash variables as a subroutine argument at all. The second option isn't the worst of both, because due to their nature Hash tables are mostly used globally and don't need to be passed to subroutines at all. Of course, a hash table could be used to store temporary results (regular expression commands), but in that case the Hash is usually declared locally and not passed to any subroutine.
Advise: Don't pass Hash variables to subroutines.
In the next post I will discuss a workaround together with the layout of the GFA-BASIC 32 Hash data type.

Visual Styles, Ocx Button, and ForeColor

2011-05-14T07:17:00.001+02:00

The BUTTON window class is the base windows class for the Command, Frame, Option, and CheckBox Ocx controls. These different OCX controls are created by passing a special BUTTON window style (BS_) in the style parameter of the CreateWindowExA() Windows API.

GFABASIC 32 Ocx	BUTTON window Style
Command	BS_PUSHBUTTON, BS_DEFPUSHBUTTON
CheckBox	BS_CHECKBOX, BS_AUTOCHECKBOX, BS_3STATE, and BS_AUTO3STATE
Option	BS_RADIOBUTTON and BS_AUTORADIOBUTTON
Frame	BS_GROUPBOX

As you can see the names of the Ocx controls conform to VB control names, which was one of the main changes in the GFA-BASIC 32 development. Another thing adapted from VB is the ability to change the controls behavior and appearance through properties. These are either changed in the Properties sidebar in the form-editor or in source code using the COM properties interfaces. In this case it doesn't matter how the appearance is changed, but how GFA-BASIC 32 implements the VB compatible behavior.

First of all, the implementation is VB compatible, but totally different. In most case (if not all) the GB32 implementation of properties and methods is much faster and cleaner. VB and VB.NET are snakes compared to the fast performance of GB32 applications. Currently, performance doesn't count as strong as in previous decades, but still. Maybe with Windows 7 for Tablets performance and size counts again. Who knows?

BUTTON drawing
The BUTTON control sends the WM_CTLCOLORBTN message to the parent window of a button when the button is about to be drawn. By responding to this message, the parent window can set a button's text and background colors. In GFA-BASIC 32 applications without the Visual Styles enabled this works as documented. However, when an application is accompanied with a manifest the new Visual Styles are applied and take precedence over the GFA-BASIC implementation.

When the Windows OS encounters a manifest file, the OS uses a different version of the common control library and globally subclasses all Windows controls, including the 'old standard' controls like the BUTTON class. GFA-BASIC 32 wasn't developed when the Visual Styles were around and uses a speedy drawing algorithm based on the classic behavior of the BUTTON class drawing. As a result, the Visual Styles improvement is not applied to the text color of the BUTTON class.

ForeColor cannot be set
Thus, the text color of Command, CheckBox, Option, and Frame Ocx cannot be changed by changing their ForeColor property when using a manifest file.
When you really need to change the text color I'm not sure how to proceed, so you are your own there...

Update Runtime Build 1170

2011-05-10T17:18:00.001+02:00

Finally the latest update of the runtime is available. Just click the Download tab at the top of the site.

What is a runtime?

The runtime is a DLL necessary to execute both GFA-BASIC 32 IDE as well as your compiled applications. The runtime is called GfaWin23.Ocx and is located in the Bin directory of GfaWin32.Exe (the IDE/Compiler). The runtime is installed in the same directory as the IDE because the Windows operating system will search the DLL in the same folder as the application. Often you will put a copy of the runtime Ocx next to your compiled application in the same directory. That way you can make sure the correct DLL is loaded.

When you download a newer runtime, like the build 1170, you must replace the GfaWin23.Ocx in your GFA-BASIC 32 directory so that the IDE will start with the newer library. In addition, when you want to use fixed commands and functions in your compiled applications as well, you should replace other copies of the GfaWin23.Ocx as well.

Maybe the GFA-BASIC 32 DLL has an unexpected extension .ocx rather than .dll. Don't let this confuse you. An ocx file is just a dll containing ActiveX controls (OCX-controls) next to other library functions. The GFA-BASIC 32 runtime code for the OCX takes about 500 KByte of the total size. The rest is just a bunch of DLL functions.

Hope this helps ...

ShowFolders Sample

2011-05-10T16:35:00.001+02:00

The ShowFolders method of the CommDlg Ocx object keeps raising questions. Therefor an example of an extended browse for folders dialog box.

The API behind the dialog box of the ShowFolders method is the SHBrowseForFolder() Shell function. Actually, there are two styles of dialog box available. The older style is displayed by default and is displayed using the BIF_ constants specified in the previous blog CommDlg.ShowFolders. However, the list of constants is a subset of the total number of flags. To specify a dialog box using the newer style, you should pass the BIF_USENEWUI flag in the ShowFolders method.

The newer style provides a number of additional features, including drag-and-drop capability within the dialog box, reordering, deletion, shortcut menus, the ability to create new folders, and other shortcut menu commands. Initially, it is larger than the older dialog box, but can be resized by the user.
The dialog box can be displayed using the following code.

Public Const BIF_RETURNONLYFSDIRS   = 0x0001
Public Const BIF_DONTGOBELOWDOMAIN  = 0x0002
Public Const BIF_STATUSTEXT         = 0x0004
Public Const BIF_RETURNFSANCESTORS  = 0x0008
Public Const BIF_EDITBOX            = 0x0010
Public Const BIF_VALIDATE           = 0x0020
Public Const BIF_NEWDIALOGSTYLE     = 0x0040
Public Const BIF_USENEWUI = (BIF_NEWDIALOGSTYLE | BIF_EDITBOX)
Public Const BIF_NONEWFOLDERBUTTON  = 0x0200
Public Const BIF_BROWSEFORCOMPUTER  = 0x1000
Public Const BIF_BROWSEFORPRINTER   = 0x2000
Public Const BIF_BROWSEINCLUDEFILES = 0x4000

Global cd As New CommDlg
cd.Title = "GFA-BASIC32 ShowFolders Demo"
cd.ShowFolders BIF_USENEWUI
If Len(cd.FileName) Then _
  MsgBox "Folder Selected: " & cd.FileName

CommDlg.ShowFolders

2011-04-21T10:01:00.001+02:00

The ShowFolders method of the CommDlg Ocx isn't documented properly. The method is included to provide an easy way to display the Shell's SHBrowseForFolders dialog box allowing the user to select a folder rather than a file. It is - of course - not part of the the Common Dialog Box Library and should have been implemented as a separately function. Or shouldn't it?

The FileName and Title properties
The CommDlg.ShowFolders(Optional flag As Variant) method shares two properties with other CommDlg methods that show dialog boxes: FileName and Title. In case these are used with ShowFolders their meaning is as follows:

- CommDlg.Title (R/W)
Sets the string that is displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user. Returns the same value as was put into it.

- CommDlg.FileName (R/W)
Sets the browse dialog box's initial selection folder (has nothing to do with filenames!). Note, by default, the SHBrowseForFolder API lets the user start at the desktop to browse the shell's namespace and pick a folder. GFA-BASIC 32 overrides this behavior by starting the browse dialog box at the folder specified in the .FileName property. To let the dialog box start at the desktop set the FileName property to an empty string. To bring up the browse dialog box with the current directory selected, set FileName = CurDir.

After closing the ShowFolders dialog box the FileName property contains the name of the selected folder. That is if you select the Ok button; after Cancel the FileName is undefined.

CommDlg code was/is buggy
The GFA-BASIC 32 library code that implements CommDlg Ocx and specifically the Show Folder function, has always been buggy and I've been fixing it many times in the past. I was confident I fixed all bugs in Build 1169. At the time of writing this blog I tried it again and I was shocked to see that it still has a bug. When you press the browse dialog box's Cancel button the FileName property is undefined and present an Access Violation error. I will fix it as soon as possible and release Build 1170, which also contains fixes for the Dlg Open/Save commands.

The optional parameter
The ShowFolders(flag) method accepts one optional argument that specifies the options for the dialog box. When you omit the argument, the default behavior is BIF_RETURNONLYFSDIRS. The flag can include a combination of the following values:

BIF_BROWSEFORCOMPUTER (0x1000)	Only return computers. If the user selects anything other than a computer, the OK button is grayed.
BIF_BROWSEFORPRINTER (0x2000)	Only return printers. If the user selects anything other than a printer, the OK button is grayed.
BIF_BROWSEINCLUDEFILES (0x4000)	The browse dialog will display files as well as folders.
BIF_DONTGOBELOWDOMAIN (0x2)	Do not include network folders below the domain level in the tree view control.
BIF_EDITBOX (0x10)	Version 4.71. The browse dialog includes an edit control in which the user can type the name of an item.
BIF_RETURNFSANCESTORS (0x08)	Only return file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.
BIF_RETURNONLYFSDIRS (0x01)	Only return file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.
BIF_STATUSTEXT (0x04)	Include a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box.
BIF_VALIDATE (0x20)	Version 4.71. If the user types an invalid name into the edit box, the browse dialog will call the application's BrowseCallBackproc with the BFFM_VALIDATEFAILED message. This flag is ignored if BIF_EDITBOX is not specified.

The BrowseCallbackProc
Although the ShowFolders method will pass most of the flags without questions asked, it doesn't honor them all. Some of the flags require an application-defined callback function to handle application defined behavior. The underlying SHBrowseForFolder API function calls BrowseCallbackProc to notify it about events. The address of the callback function is passed in the BROWSEINFO structure that contains information used to display the dialog box. The GFA-BASIC 32 ShowFolders method uses the callback proc to select the folder set with CommDlg.FileName in response of the BFFM_INITIALIZED message. GFA-BASIC 32 does not provide a way to interact with its BrowseCallbackProc, making ShowFolders a simple folder selection mechanism.

An Array of Pointer To

2011-04-10T07:48:00.001+02:00

The "Pointer To" data type isn't a key feature of (GFA-)BASIC. A BASIC programmer should not be bothered with pointers, at least that is the consensus. If you like to know more about pointers in GFA-BASIC check out ByRef arguments are Pointer To variables.

Introduction
One of the many variants of "Pointer To" I never considered; a declaration of an array of type "As Pointer To type" . For example, what does this do?

Dim a(1) As Pointer Large

It turns out that (with Option Base 0) the array contains two elements (0,1) of int32 data type. Two Longs are allocated and not two Large variables (int64). The same is true of all other types. Due to the Pointer keyword the elements are only 32-bit wide and are initialized to Null.

Code
This time I don't present a smoking explanation but sample code only. It contains 3 examples of 3 different array types, but they are all of Pointer To. See what happens.

' Essentially, it is an array of 32-bit integers
' to hold addresses of memory locations.
' The array's data type determines how to use
' the address stored in the elements.

' Example 1 - Array as a Pointer To Large

Dim a(1) As Pointer Large
Trace ArraySize(a())    ' 8 bytes, thus 2 * 4 bytes

' Assign memory locations to the elements:
Dim il As Large = 9, jl As Large = 10
Pointer(a(0)) = V:il     ' set array-elem to address of i
Pointer(a(1)) = V:jl

' Due to "As Pointer To Large" GFA performs
' an indirect access using the addresses stored in
' array elements. It does NOT directly return the
' values stored in a(0) or a(1) (which are memory locations).
Trace a(0)              ' = 9
Trace a(1)              ' = 10

' How does GFA do this?
' Well, let us see what is actually stored in a(0) and a(1).
' We use ArrayAddr() to obtain the addresses  of the array elements and then Lpeek the address stored there and then use Large{adr} to obtain the value.
Dim adr As Int
adr = Int{ArrayAddr(a()) + 0}   ' a(0)
Trace Large{adr}                ' = 9
adr = Int{ArrayAddr(a()) + 4}   ' a(1)
Trace Large{adr}                ' = 10

' Example 2 - Array as a Pointer To String
' Again an array of 32-bit integers, but now they must
' be set to point to the string's descriptor.
Dim s(1) As Pointer String, st As String = "Hello"
Trace ArraySize(s())    ' still 8 bytes
Pointer(s(0)) = *st     ' assign string descriptors
Pointer(s(1)) = *st     ' assign string descriptors

' See how GFA correctly uses the addresses to
' obtain the strings:
Trace s(0)              ' = Hello
Trace s(1)              ' = Hello

' Internally handled as:
Trace Char{{{ArrayAddr(s()) + 0 }}}
Trace Char{{{ArrayAddr(s()) + 4 }}}


' Example 3 - Array as a Pointer To UDT
' Again an array of 32-bit integers, but now they must
' be set to point to instances of ArrayDesc type.
Dim ad(1) As Pointer ArrayDesc
Trace ArraySize(ad())    ' still 8 bytes

' Use ArrayDesc of previously declared arrays
Pointer(ad(0)) = *a()    ' assign addr of ArrayDesc a()
Pointer(ad(1)) = *s()    ' assign addr of ArrayDesc s()

' See how GFA correctly uses the addresses
Trace ad(0).ptype              ' 37 ($24 + $1)
Trace ad(1).ptype              ' 73 ($48 + $1)

' Internally handled as:
Trace Int{{ArrayAddr(ad()) + 0 } + 4}
Trace Int{{ArrayAddr(ad()) + 4 } + 4}

Type ArrayDesc
  -Int    Magic         ' 4 Byte ASCII
  -Int    ptype         ' vtType
  -Int    size          ' size of the datatype
  -Int    dimCnt        ' number of dimensions
  -Int    dimCnt2       ' Erase and $ArrayChk
  -Int    paddr         ' ArrayAddr()
  -Int    corr          ' correction value
  -Int    paddrCorr     ' void*addrCorr;
  -Int    anzElem       ' number of elements
  -Int    sizeArr       ' size in bytes ArraySize()
  -Int    Idx(3)  '[3][1];      //Open Array
EndType

Note - A declaration of an array creates an array descriptor which the array variable references. Operations on the variable are performed using the content of the descriptor. This is not about the array descriptor, but it illustrates what is allocated with Dim. The UDT ArrayDesc is used as an example for an array of Pointer To UDT.

Conclusion
GFA-BASIC 32 returns the content of array elements correctly, but this only works when the array elements are assigned the addresses of memory locations that need to be read using the arrays data type.

Status of GFA-BASIC 32

2011-04-09T10:07:00.001+02:00

It has been a while, but I certainly didn't give up on GFA-BASIC 32. In fact, I've done some fundamental research this winter to figure out a (new) direction for GFA-BASIC 32.

COM is a must
Each new Windows OS provides more COM based interfaces, rather than new DLL function APIs. A modern language must support the use of COM interfaces, and I've done a lot of research in that area. The first step in the process should be the use of non-ActiveX COM libraries. This requires adding COM references to a GFA-BASIC 32 project. Once this is completed, the language should have the ability to provide COM classes as well. So, in the next stage, GFA-BASIC 32 must support object-oriented structures like VB's Class/End Class. Finally, research must be done to evaluate the opportunity to add third party ActiveX controls.

Maintaining GFA-BASIC
This is not the only thing that is on my mind. I often get questions or receive bug reports that require a lot of time to investigate. I only have a heavily commented disassembly, I still don't understand all of it. Once I found a bug or improvement it needs to be implemented. Well, patching is an art in itself and often can be done in multiple ways. Sometimes I need to acquaint myself with entirely new ways of hacking. This costs too much time, so I need to figure out how to proceed with that. My first priority is to implement COM support.

Assemble in GFA-BASIC?
But, only recently (!) I realized I could maybe copy the disassembly to GFA-BASIC 32 and use GFA-BASIC's assembler to re-create the executable (GfaWin32,exe). I made some trials and it might actually work! That would mean I could edit the (assembly) code of the IDE directly inside GFA and then recompile (F5). Wow, maybe I give this my number one priority ...

Next blog entry
One of the questions I received contained a statement I wasn't familiar with. The code contained a declaration of an array of type "Pointer To Int". I had no idea what that meant. Do you? If not check out the next blog.

Download new update; Build 1169

2010-11-28T09:00:00.002+01:00

NOTE Due to a new version of the runtime GfaWin23.Ocx, this Blog is updated on 28 Nov 2010.

See: http://gfabasic32.blogspot.com/2010/11/update-of-build-1169-2.html

November 2010 is a good time to review prior updates and decide to upgrade to build 1169. That is, the IDE/Compiler (GfaWin32.Exe) is updated to build version 1169, but the Ocx/runtime (GfaWin23.Ocx) has build version 1168. The About dialog box has been slightly revised and will show you the correct versions.

There are two downloads, both contain the 28 Nov 2010 update of the runtime Ocx, pick yours:

gb32.zip – Contains the full GFA-BASIC 32 package (for new users).
gb321169.zip – Contains Exe, Ocx, and revision history only.

Ocx/runtime
The runtime has been patched to fix the most recent reported bugs. Somewhere on the internet there is a bug-list, but the list confuses features with bugs and some bugs aren't really bugs. For instance, the ToolBar.Clear method is supposed to be faulty. However, like the Panel object, each Button object must have a key index. The collection items Button and Panel are removed by there key name and not by there index number. If you miss something, please ask.

Library files
A new update was also necessary because loading $Library files is still error prone. I fixed a bug I simply discovered after creating a minimal lg32 file. So, it isn't that hard to find a bug and it isn't that hard to report it. I urge you to test your erroneous library files and strip them to the bone until the bug remains clearly. Then post the source to gfabasic32@gmail.com and I will investigate as soon as possible.
The library file is going to be an important part in a new GFA-BASIC version that will support classes (OOP) and more COM. So, help me build a better GFA-BASIC 32.

Report Bugs
Please report bugs or questions concerning possible bugs to the mailing list or to me directly. There is no need to "panic" when something doesn't work as expected. After researching the disassembly for so many years I'm impressed with the clean and consistent programming of GFA-BASIC 32.

Update of Build 1169 (2)

2010-11-28T08:57:00.000+01:00

This is the second update of Build 1169. The IDE (GfaWin32.exe) isn't changed and still has build number 1169; however the runtime in the previous build-release 1169 (1) contained a new bug.

The CommDlg property .FileName didn't return the selected folder when CommDlg.ShowFolders was used. This is now fixed and the .FileName property should now return the correct filename(s) or folder. Note that the .FileName property was associated with three bugs. I hope they are all fixed now.
The runtime has build number 1169 now as well.

GOTO DOWNLOAD

ImageList Ocx Part 2

2010-11-22T13:22:00.001+01:00

In the introduction to the GFA-BASIC 32 ImageList Ocx (1) the emphasis was placed on the creation of the image list common control, which – as we saw - is delayed to the moment the first picture is added to the control. All images have the same size. The size is determined by the first picture's height and width, or the size values set using the .ImageWidth and .ImageHeight properties of the ImageList Ocx. The .ColorFormat property specifies how the pictures are added and whether or not a mask is generated. The color for the mask is specified using the .MaskColor property.

After the creation
Once the underlying image list common control is created, the .ColorFormat, .ImageWidth and .ImageHeight properties fail to accept a new value. These properties raise the E_FAIL COM error. This is also demonstrated when you use the 'ImageList Data' dialog box to add images to an ImageList Ocx. The upper left controls contain the options to create the image list common control. You may specify the required size and color format. The default settings are zero for both the size properties, and the 0 (device dependent/mask included) ColorFormat property.
After adding an image these control are disabled, because ImageList_Create() has been invoked using the settings from these controls.

Using masks in GFA-BASIC 32 is a bit confusing because its setting is the opposite of Windows API.

Masks in GFA-BASIC 32
By default GFA-BASIC 32 creates a mask for each and every picture you add to the ImageList control. Whether or not the mask is added to the underlying image list common control is determined by the .ColorFormat property value.
In contrast with the API specifications, GFA-BASIC 32 uses a reversed setting for the mask option. The flags argument in the ImageList_Create() function specifies the mask using the ILC_MASK bit value. In GFA-BASIC 32 you don't explicitly specify a mask by setting bit 1 to 1; in GFA-BASIC the .ColorFormat value must hold a zero value in bit 1.

.ColorFormat = 0 '(default) create mask
.ColorFormat |= 1 ' no mask

Just before creating the image list common control GFA-BASIC inverts the first bit and includes it in the flags parameter passed to the ImageList_Create() function.
However, when you explicitly exclude a mask (by setting .ColorFormat |= 1) GFA-BASIC 32 will continue to create masks. However, when picture and the mask are added they are simply ignored by the image list common control.
Note Excluding a mask will result in loss of data when you add an icon to the image list. Therefore GFA-BASIC 32 uses a mask at all times.

Purpose of UseMaskColor and MaskColor Properties
When you add an icon into the list, GFA-BASIC uses its internal mask. If a bitmap or a metafile is added, a mask is created in memory. When .UseMaskColor == 0 the mask is simply a black monochrome bitmap of the same size, all pixel bits are set to zero. However, when you set .UseMaskColor to a nonzero value, the pixels in the image that have the same color value as the .MaskColor setting have a corresponding white color in the monochrome mask bitmap. This opens up the possibility to draw the image transparently. How the image is drawn later depends on more factors than the availability of a mask bitmap only, however.
You can change both UseMaskColor and the MaskColor properties before adding the next image to the list. That way you can have GFA-BASIC generate the correct mask for the image to add. (Each image might have a different transparency color.)
UseMaskColor and MaskColor are a per image setting when adding a Picture to the list.

The BackColor Property
The only property we didn't discuss so far. The .BackColor property isn't used in the creation of the image list common control and it isn't used in the addition of images to the list. The .BackColor property setting is used when we want to get something out of the image list control. It is used in drawing operations and when a Picture object is retrieved.

The .BackColor is used in the ListImage.Draw method. The .Draw method is simply a wrapper around the ImageList_Draw(himl, i, hdc, x, y, fStyle) API, which draws an imagelist item in the specified device context. The fStyle parameter is used to set the drawing style and only when fStyle = ILD_NORMAL (0) the image is drawn using the background color. You can experiment with this, it speaks for itself.

Note The .BackColor value is passed to the underlying common control using ImageList_SetBkColor() API.

The .BackColor setting is also used when the ImageList control is used with other controls (that can't be bound to the ImageList control). You can assign the ListImage.Picture object of the ListImage item to the .Picture property of another control. For example, the following code assigns the Picture object of the first ListImage object in a ListImages collection to the Picture property of a newly created StatusBar panel:

Dim pn As Panel
Set pn = sb.Panels.Add() ' Add a new Panel object.
Set pn.Picture = im1.ListImages(1).Picture

However, how is this Picture created? That is , how are single Pictures extracted from the image list control? Can this be done by invoking some ImageList_Xxx() API function? The answer is no, the Picture property is a GFA-BASIC 32 specific implementation which uses the .BackColor setting.

The Picture property
With .Picture (Get-property) GFA-BASIC allows to create a new bitmap from the image list (and its mask). It creates always a 24 bits DIB memory bitmap to draw the image using ImageList_Draw(). The size of the DIB is ImageWidth x ImageHeight and the background is cleared using the color from .BackColor setting. Then, GFA-BASIC uses the ImageList_Draw() API to draw the specified image using the API background color for the image list (which is also set with .BackColor property!). The net result is a bitmap with a background color .BackColor.

Since the .Picture property returns a 24 bit DIB only, possibly transparent, the new obtained image form the ImageList Ocx might be quite different from what first was added. The .Picture property only returns device independent bitmaps or icons. Any jpg and metafile images are converted to a DIB.

ExtractIcon
When you require a transparent image for some other control that accepts an icon use the .ExtractIcon property instead. This will return a real Windows icon resource which is transparent by default.

ImageList Ocx (1)

2010-11-22T12:19:00.000+01:00

An ImageList control is a collection of images of the same size and type. An image list control helps you manage a collection of images that are the same size, such as bitmaps or icons. Image lists, which are designed for use with list view and tree view controls, manage images but do not display them directly. In BASIC its use is extended to be repository for other controls as well.

Note Part 2 was published before part 1, so might have read ImageList Ocx (2) before.

The API behind the creation
The windowless ImageList Ocx is a bit different from the image list common control. Although the GFA-BASIC 32 Ocx is created using the API function ImageList_Create(), the underlying image list common control is managed using a second layer of ListImages, another Ocx type. The ListImages object is created when the ImageList Ocx is created and both are initially 'empty'; there is not even a real image list common control. GFA-BASIC 32 doesn't create the underlying image list control before the first picture is added to the list. The reason behind this behavior will be clear when you look at the definition of ImageList_Create(). The image list needs the initial size of the images and most often the size isn't known until the first image is added.

hIml = ImageList_Create(cx, cy, flags, cInitial, cGrow )

This function creates a new image list common control and returns the handle to the image list if successful. Note that the handle isn't a handle to a window (hIml isn't HWND type).

To be able to create a proper ImageList Ocx, the following parameters and Ocx properties need to be set.

Only three properties determine the type of image list common control is created.

.ImageWidth and .ImageHeight are used to set the cx and cy arguments of the API function. When not specified the first image added to the list determines the width and height of all images (cx and cy).
.ColorFormat is used to set flags API parameter, which specifies the required image type (16 colors, true colors, etc.). Default is device dependent with a mask.

Masks
The .UseMaskColor and .MaskColor properties are useful only when the control has a masked bitmap attached. The masked-bitmap is created when the API argument flags includes ILC_MASK (GFA-BASIC default). If the ImageList Ocx doesn't contain a masked bitmap these two properties have no effect!

A non-masked image list includes a color bitmap that contains one or more images. This is a wide bitmap containing small bitmaps. When a non-masked image is drawn, it is simply copied into the target device context (DC); no special processing occurs.
A masked image list includes two wide bitmaps of equal size. The first is a color bitmap that contains the images; the second is a monochrome bitmap that contains a series of masks (one for each image in the first bitmap). The mask is created by GFA-BASIC 32 and not by Windows, except for icons. Icons contain both a color bitmap and a mask and GFA-BASIC adds directly to the underlying common control.

On output, when an image is retrieved from the ImageList Ocx, the existence of a mask determines how the image is composed. An image can be drawn using ImageList.Draw or extracted using ImageList.Picture or ImageList.ExtractIcon.
With a masked image present, the mask is combined with the image itself. This combination produces transparent areas in the bitmap in which the background color of the target DC shows through. More about this is ImageList Ocx (2).

The Picture input Object
The ImageList Ocx only accepts images contained in a Picture or StdPicture object. A Picture Ocx object is a container for a bitmap, icon, jpg, or metafile image. In both VB and GB32 it is not possible to assign any other type of image than a Picture COM type.

There are three ways to obtain a Picture object.
1. Use LoadPicture() to load an external image file.
2. Use CreatePicture() to create a picture object initialized with a bitmap or icon.
3. Obtain a Picture object from another COM object.

All Picture objects (jpg, bmp, dib, emf) that are added to the ImageList Ocx are provided with custom created mask. The masked image is created by GFA-BASIC using the color from the .MaskColor property, but only when .UseMaskColor is True. .UseMaskColor and .MaskColor determine the transparent color per image.

Adding Pictures – API details
Once you have an image in a Picture object, you can start adding that image to ImageList Ocx. Internally, GB32 has a choice from three possible API functions to add a Picture image: ImageList_Add(), ImageList_AddIcon(), and ImageList_AddMasked() [not used by GB32]. Obviously, GFA-BASIC uses ImageList_AddIcon() when the Picture object holds an icon resource. In all other circumstances it uses the ImageList_Add() API which takes three arguments:

index = ImageList_Add(himl, hbmImage, hbmMask)

When you add an image into the list, GFA-BASIC gives it a mask. If the image is an icon, its internal mask is reused. If it is a bitmap or a metafile, a mask is created. The end result is a collection of icons of the same size. However, all images in an image list are contained in a single, wide bitmap in screen device format. When an image list includes a mask, it also has a monochrome bitmap that contains masks used to draw images transparently (icon style).

Before invoking this function, GFA creates the hbmImage and the hbmMask. The hbmMask is a black bitmap in case .UseMaskColor = False (0).

Finally
Usually, the ImageList Ocx is used as an image repository for other Ocx controls. When you attach an ImageList to another control, you don’t need to worry about what gets drawn and how. An image list is a collection of images of the same size, each of which can be referred to by its index or key.

A second blog ImageList Ocx (2) discusses more implementation details.

Initializing an Arrray

2010-08-05T10:50:00.001+02:00

An array is a named collection of values of the same type. In BASIC an array is always dynamic, the memory necessary to store the array elements is allocated at runtime. You cannot set the array elements to a constant value before hand. Initializing array elements is a runtime operation performed after the array is created, unfortunately. Let me illustrate.
In C/C++ you can assign initial values to an array by enclosing values within braces {}. For instance

int scores[5] = {1, 2, 3, 4, 5};

In contrast with BASIC, the array is static and not created dynamically at runtime. The C/C++ compiler reserves 5 consecutive integers (each 4-bytes, thus 20 bytes) in the .rdata section of executable and associates the address with the variable name scores. When the executable is loaded the 5 integer values are loaded as well and scores points to the first integer (value=1). Because the array is of type int (32-bits integer) the C/C++ compiler converts the ASCII representation "1" found in the source code to the 32-bits number 1. The executable contains the following array data, assuming the scores is stored at 0x0498760:

variable	address	value
scores[0]	0498760	1
scores[1]	0498764	2
scores[2]	0498768	3
scores[3]	049876C	4
scores[4]	0498770	5

In C/C++ the initialization is performed at compile time. So, when the C/C++ program is started no time is spent on assigning values to the array elements.
This in contrast with (classic) BASIC. The only method of initializing an array is by explicitly assigning each value to the array elements. Often, the values are stored in a DATA statement and then assigned using READ in a For-Next loop. To accomplish the same in BASIC you will often see the following code.

Dim scores(4) As Int, i As Int
For i = 0 To 4
  Read scores(i)
Next
Data 1,2,3,4,5

At compile time, the compiler doesn't know the data type of the Data-items. This is determined by the datatype of the variable used in the READ command and known at runtime only. After compiling the values in the Data line are stored as ASCII strings. The Read command converts the ASCII "1" to a 32-bit integer (because scores() is declared as an Int). After READ completes the conversion of the first value, it increments the data-pointer _Data. The next Read statement converts the next string ("2") using an ASCII-to-Int function. (The runtime function used is READINT() ). A rather clumsy, inelegant, and (run)time consuming process. Fortunately, GFA-BASIC 32 provides a faster way to initialize an array, thereby skipping the ASCII-TO-INT process for each element. BASIC doesn't allow array access through pointers, so the dynamic allocation remains.

The Array command
To initialize an array with literal constants GFA-BASIC 32 offers the Array command. The Array command takes a string with data in binary format to initialize the elements.

Array scores() =  Mki$(1, 2, 3, 4, 5)

The string is nothing more than a container for the data; a piece of memory containing the values in their binary form. And, most importantly, the string is created at compile-time. The string data is stored in their binary 32-bit format (Mki()) and takes 5 * 4 bytes = 20 bytes in your program's code. The storage is the same as with an initialized C/C++ array. The Array command uses the length of the string to calculate the number of elements to create a one-dimension array. It then copies the data to the array. This process is about 6-8 times faster than the For-Next loop method.

Unsigned to signed Byte data type

2010-07-20T12:39:00.001+02:00

GFA-BASIC 32 provides two unsigned integer data types, the Card and Byte data type. The Card is a 16-bits integer and allows you to store positive integral values in the range from 0 to 65535. The Byte is 8-bits data type allowing you store a positive value from 0 to 255.

It is not important how many positive numbers the data type can hold. More importantly is the way how these values are handled in case of mathematic operations. The default operation GFA-BASIC 32 allows on integers is signed arithmetic, because all other integer data types are signed types. However, when you include a value stored in a Card or Byte GFA-BASIC expands the value to an unsigned 32-bits integer before using it in a calculation. So, when you store 255 in a Byte, the value 255 is used in calculations.

Now, suppose you need to use a Byte to store values like: –1, 0, 1. (The GFA-BASIC 32 editor uses these values to store line indenting information and I used it to implement block folding.) You can simply store these values into a Byte and in case of –1 all bits of the byte are set resulting in $FF (=255).

Dim b As Byte = -1  ' b = 255 ($FF)

When the Byte is used in a calculation, the value 255 is applied, which is not what we want. We need the Byte to behave as a signed value; $FF must be interpreted as –1. For this to happen we must GFA-BASIC 32 tell to interpret the Byte as a signed byte explicitly using the Sbyte() function. The Sbyte(b) function forces a conversion to a signed expansion to 32-bits.

Dim b As Byte = -1  ' b = 255 ($FF)
i% = b           ' i% = 255
i% = Sbyte(b)    ' i% = -1

In fact, the compiler uses a different assembler instruction to move the value from memory to the eax register (movzx eax, mem).

Accessing a C array

2010-07-02T10:52:00.001+02:00

A C-compiler treats arrays as pointers. An array-variable points to the first element. C computes the address of an array element by multiplying the element index with the size of the data type. This is
automatic behavior of C. A pointer is an 32-bits integer holding an address pointing to a specific type. For instance, the next declaration defines a pointer to an array of 16-bit integers. To be effective it needs to be assigned an address first.

short* parr;
parr = 0x0180980;

The variable parr references the Short (int16) at the given address. To read the value at the address:

short value;
value = *parr;

Incrementing the pointer with one will let the pointer reference the next element, not the next memory location! E.g. parr++ will result in 0x0180982 (+2). Pointer arithmetic includes the size of data type.

parr++;
value = *parr;

Accessing the fifth element in the array:

parr += 5; value = *parr;
value = *(parr + 5) ; // even shorter

Almost the same can be simulated in GFA-BASIC 32 using the Pointer-type. Except GFA-BASIC does not use the size of the data type into pointer arithmetic. A Pointer variable defines the type of the variable without an address, like C.

Local parr As Register Pointer Short
Pointer(parr) = 0x0180980
Local Short value 
value = parr

To obtain the value from the address GFA-BASIC 32 doesn't provide an indirection operator as C does, as in value = *parr. In GFA-BASIC 32 you must first assign the pointer variable an address using Pointer(parr)= addr. Once the pointer variable is assigned an address, it can be used as a normal variable. Note that Pointer()= performs an kind of implicit VarPtr(parr) = addr, because a pointer variables VarPtr == Null.
Incrementing the pointer to point to the next element requires to set the variable's VarPtr to the next address, in this case plus 2 (SizeOf(Short)==2). So, first give the variable a new address and than access the address using normal variable syntax.

Pointer(parr) = Pointer(parr) + SizeOf(parr)
value = parr

The next sample shows how to iterate over a C- array and how to access an element by index.

Dim C_str As String = "Hello"

' Iterating a C-array
Dim parr As Pointer Byte
Pointer(parr) = V:C_str
Trace Hex(Pointer(parr))
While parr <> 0
  Debug Chr(parr);
  Pointer(parr) = Pointer(parr) + SizeOf(parr)
EndWhile
Debug
Trace Hex(Pointer(parr))

' C-array using index
Pointer(parr) = V:C_str + 4 * SizeOf(parr)
Trace Chr(parr)

The code uses the Debug Window and shows the begin and ending address of the variable parr. The Debug commands show the byte (in character format) the parr Byte variable is addressing.

A GFA-BASIC32 Forum

2010-06-27T08:04:00.001+02:00

I'm joining a forum now.

http://gb32.proboards.com/

The administrator Detlef Peters AKA 'Joshy' convinced me of the relevance of this forum. He has created plug-ins, DLLs, libraries to be used with Basic4GL, but he thinks this language is dead and no longer supported. He also thinks that quite some Basic4GL users might switch to GFA-BASIC 32. They are welcome and might need technical support. Joshy seems knowledgeable and serious, and therefore I decided to join, although I don't like forums, I prefer mailing lists, but what the heck I'll give it a try.

I will check in as much as possible, but will limit myself to answering GFA-BASIC 32 related questions and problems. General Windows programming issues should be solved by studying (VB) books and other samples. For me, it is no longer opportune to answer questions like "what is the difference between ByVal and ByRef?" The internet is full with good explanations. I will go into questions of why you should use ByRef explicitly in non-event Sub subroutines

Exe without runtime?

2010-06-13T08:43:00.001+02:00

One of the questions I got is:

"There is a possibility that my program e.g. "name.g32" run as "name.exe" after compiling without using "GfaWin32.Ocx" ?
If yes, can you give me instructions for this please ?

At the first beta introduction of GFA-BASIC 32 back in 1998 we asked the same question. Why wouldn't it be possible to statically link the necessary code into the EXE? That would give us a slightly larger EXE, but the result would be one file. There are two reasons why this isn't possible.

The entire interface of a GFA-BASIC 32 program is encapsulated in to COM objects. All COM objects are related to each other and thus the stand-alone EXE would increase with about 500 KBytes. GFA simply choose to put the code in a single (in contrast with VB!) OCX runtime. Putting OLE/COM stuff in a DLL is common to all programming languages.
The Windows OS is capable of sharing one instance of a DLL with multiple EXEs. Not only your EXE depends on the runtime, but the IDE does as well. All instances of your programs and all instances of GFA-BASIC 32 IDEs share this one DLL.

Mailinglist off-line

2010-06-13T08:26:00.001+02:00

It seems the gfa@liebenstein.de mailinglist is currently offline. I hope this will be fixed soon, otherwise we will have to look for an alternative. For the moment, if you have urgent questions you can ask me at gfabasic32@gmail.com.

New 'old-GFABASIC 32- samples'

2010-06-10T09:23:00.001+02:00

Harald Bonsel posted me the following:

"I found an old directory of GFA ftp://ftp.gfa.net/pub/gfa/

. May be you out the link on your Google page?"

It turned out that the old site contains some never published samples. so check it out.

Be a game-programmer!

2010-06-10T09:19:00.001+02:00

I've ported MiniB3d (a library, originally developed for BlitzMax, http://blitzbasic.com/ ) to a DLL that can be used in FreeBasic, or GFA Basic.

Another FreeBasic user, named super-castle, made include files to use it in GFA basic.
http://www.freebasic.net/forum/viewtopic.php?t=15794
http://www.freebasic.net/forum/viewtopic.php?t=15409

MiniB3D features:
- simple access to OpenGL graphic.
- primitives like CreateCube, CreateCone, CreateSphere...
- animated models
- collisions
- quaternion-based rotations (very useful for flight simulation)
- LOD terrains
- and much more.

I hope that you may find it useful.
Bye!
Angelo Rosina
angros47@yahoo.it;

An introduction by Troy H. Cheek

2010-06-06T11:49:00.001+02:00

On Apr 13, 2009, Troy H.Cheek wrote on his blog about GFA-BASIC: "While there are websites just chock full of VB, QB, and even GFA programming goodness, most of them seem to assume a level of knowledge that your average enthusiast (or even an above average one such as myself) just doesn't have yet. It's all well and good to fill a GFA-BASIC 32 Stuff blog full of articles about "ANSI API functions and RichEdit" and "GetFirstVisible method not implemented", but I'll be the first to admit that I'm not sure what any of that stuff means. Heck, much of "Pointer and Gfa_Var object" was over my head. I guess what I'm asking is this: Where are the websites for down and dirty little GFA BASIC programs? You know, the type that the average man on the street (well, geek in the lab) is actually going to write?"

Well, Troy wrote a series on one: "Roll Your Own GFA BASIC Program 1"

Swap two characters

2010-06-06T11:08:00.002+02:00

I am a bad typist. I often hit the wrong keys on my keyboard. I never learned to type using 10 fingers, I only use one finger a time. The faster I type the more errors I make. It turns out however, that two kind of errors show up most frequent.
The first error concerns hitting the wrong key. Most often I hit the key next to the key I want to press. I have to go back to the position have to delete the character and retype the correct letter. I cannot speed up this kind of restoring.
The second typing error I often make is hitting keys in an incorrect order. An incorrectly spelled keyword in GFA-BASIC 32 marks the source code line in "error-state" after hitting [Enter]. That is the moment I realize I mistyped something. For instance:

Locla Bool fCommentLine

This kind of error is very easy to correct. Put the caret between the l and the a and then hit Ctrl-T. This swaps the two characters at either side of the caret.

Initializing Variables

2010-05-30T12:22:00.002+02:00

What value does a variable have when you first declare it, and what happens if you try to read it before you initialize it? And how do you get an initial value into a variable?

Ocx initialization
Take a look at control and form properties. You initialize them as much as possible at design time in the Properties window. In contrast with VB, GFA-BASIC 32 needs extra code to initialize the item properties of every Ocx that supports a Item collection (ToolBar.Buttons; Status.Panels; etc). Initialization is so important to control and form properties that GFA-BASIC should be extended with more property pages to initialize items at design time. For example, we could use a property box to initialize the strings of a ListBox control at design time, a task you have to perform at run time now.

Initializing variables in general
In some languages, uninitialized variables have a semi-random value. In C, for example, local variables (but not global or static variables) are undefined. If you want an initial value, you must give it. Fortunately for C programmers, this is easy to do. An undefined variable is a disaster waiting to happen, and careful C coders initialize their variables as close to declarations as possible. In contrast, GFA-BASIC 32 always initializes all variables whenever they are declared. String variables are initialized to a "Null-String", numeric variables are initialized to 0, Variants are initialized to Empty, and object variables are initialized to Nothing.
This difference fits the philosophies of C and Basic. C doesn’t initialize variables to a default because local variables must be initialized at run time. This has a cost, and C doesn’t do any run-time work unless you ask for it. Undefined variables are dangerous, but that’s your problem. GFABASIC 32 is more concerned with safety. If you declare an array of 5000 Integers, GFA-BASIC 32 will initialize them all to 0 even if it takes extra run-time work to do so.
However, 0 or Empty might not be the initial value the program needs. In C, you can combine the declaration of a variable with its initialization:



int cLastWindow = 20;

Even arrays can combine a declaration and initialization.

Fortunately, GFA-BASIC 32 allows declaration and initialization in one statement:



[Global] Dim iCountMax As Integer = 23

This usually works fine, and by using the Global statement global variables can be declared in any procedure. GFA-BASSIC 32 doesn't provide a 'Declarations section at the top' like VB, so we must take care when and where we declare global variables. The problem is that initialization-while-declaring requires executable code, the default value must be copied to the variable's memory location.

You need to find some logical place to put the declaration & initialization. That place must be reached only once—either when the program is executed or the first time the variable is accessed.
Global vs Static Variables
A Static variable is a global variable as well. The difference is that a global variable is visible to all parts of your program, while static variables have an implicit Local clause in front of it. They are only accessible inside a procedure. (Note - A Static variable in the main part of the program is local to the Main section only.) The Static variable can be initialized in a combination with a declaration:

Static fFirstTime As Boolean = True

A Static variable is only initialized once the first time the subroutine is executed. Would you use a global variable declaration & initialization inside a subroutine, the global variable would be initialized over and over.

Virtual-key code to ANSI character

2010-05-16T11:54:00.001+02:00

The Ocx_KeyDown event and the function Gfa_KeyGet (GFA-BASIC editor extension) provide a virtual-key code representing the key pressed. However, it doesn't take the shift-state into account. (The Screen_PreView event sub passes WM_KEYDOWN messages as well.)
In all cases you want to process a WM_KEYDOWN message the ANSI character isn't known. To convert a virtual-key code plus a shift state to an ANSI character you need ToAscii() API. This function takes the virtual-key code and the keyboard state and translates it to an ANSI character. I use it as follows:

' Press shift-key than click mouse
Do :   Sleep : Until MouseK
Trace Chr(VkKeyToAscii(65))
Trace Chr(VkKeyToAscii(Asc("8"))) ' –> *

Function VkKeyToAscii(keycode As Int) As Int
  Dim sb As String * 4

  Static Dim keyboardState(256) As Byte
  ~GetKeyboardState(ArrayAddr(keyboardState()))

  If ToAscii(keycode, 0, ArrayAddr(keyboardState()), sb, 0) == 1
    Return Asc(sb)
  Else
    Return 0
  EndIf

EndFunc

DefMouse

2010-05-13T18:07:00.001+02:00

DefMouse is an hold over from previous GFA-BASIC versions, but is still – with a little twist - supported in GFA-BASIC 32. In GFA-BASIC 16 bit DefMouse was used to set the mouse shape for the entire screen. DefMouse changed the mouse globally, for each GB window and control, as well as for the desktop. With GB32 the mouse-cursor shape is set for each OCX object individually, which is much more flexible. Now, the general way of setting a mouse-cursor is by setting the control's MousePointer, MouseCursor, or MouseIcon property, either at design-time or at runtime.

DefMouse 0 is the secret
GFA-BASIC 32 tries to be as compatible as can be with previous versions, so the DefMouse command had to be implemented as well. It works, however the region is now limited to GFA-BASIC windows (and controls) only. An improvement, wouldn't you agree? How does that work? How does GFABASIC prevent corrupting mouse pointers? The solution to the problem is the DefMouse value. When DefMouse == 0 (or basDefault) the individual mouse settings of the Forms and controls are used. However, when DefMouse n (where n <>0) is used to select a new mouse shape the individual OCX mouse settings are ignored. On the plus side, you are guaranteed with the new mouse shape over every(!) OCX control/form. To revert to the individual settings you must invoke DefMouse 0.

A Popup window
A Popup selection menu is a system window executed in the context of the GFA-BASIC 32 application. It isn't an Ocx object (it should have been!) and has no private mouse settings. Especially when a Popup is used from within a TrayIcon Ocx GFA-BASIC 32 has to revert to the DefMouse setting. However when DefMouse = 0 GFA-BASIC does nothing, because it expects to handle the individual Ocx mouse settings. The WM_SETCURSOR message isn't handled properly an a random cursor value is used to tell the system (Windows) which cursor to use. The mouse cursor is drawn incorrectly when showing the popup menu. Consequently, the global mouse must be set to a non-zero value before invoking Popup, for instance DefMouse basArrow. When Popup returns the global mouse setting must revert to zero: DefMouse 0.

Screen Ocx
The Screen Ocx supports the MousePointer, MouseCursor, or MouseIcon properties as well. These operate exactly the same as DefMouse, eg on the global mouse setting. Thus DefMouse can be replaced by Screen.MousePointer = n, where n is a basXX mouse value.
The DefMouse command can also be passed a string containing a bit-pattern to create a custom (monochrome) mouse.
The Screen.MouseCursor on the other hand accepts a MouseCursor object (a real Windows cursor resource in an external file). In addition, Screen.MouseIcon accepts a Picture object. So, there many different options to create a custom – global – mouse shape.

Replace a Toolbar's button image

2010-04-24T09:19:00.001+02:00

Back in 2000 a bug report was posted describing how GFA-BASIC 32 failed to properly remove a Toolbar Ocx button. I say properly, because the button was removed, but the button count remained the same. Now in 2010 another bug was reported. The button's image couldn't be easily replaced, because the button's property .Image isn't implemented. So, the Ocx Toolbar has some flaws ....

To address the new bug, we need to find a work-around. This is easy, we must invoke Toolbar.Remove index to remove the button and than Add it again with the new image index. But for this to work properly we also need to know why Toolbar.Remove index failed in the first place. Well, the cause for the failure was quickly found; the .Remove method failed because the button wasn't assigned a key. The Toolbar's Add method takes the following (optional) arguments. Each argument is a Variant, GFA-BASIC converts the argument to a proper data-type internally.

ToolBar.Add index, key, caption, style, image

index - defines the position of the button.
key – specifies a character string used to store and retrieve the button by name.
caption – defines the string to display next to the button.
style – specifies the type of button.
image – is a key specifying the image to use from the ImageList control.

ToolBar.Remove index requires the index (== position) of the button to remove. Subsequently, most of us don't specify a key for the button, we don't need it later, do we?
Well, as a matter of fact, GFA-BASIC 32 uses the key to remove the button from the underlying Buttons collection, if it isn't specified it cannot be removed. Despite the fact that Remove requires the index (or position) only, it requires the accompanying key to actually remove. So, add a key argument to ToolBar.Add and you are good.

Now we know how to remove a button we can insert a new one. To accomplish this we must use the index argument of Add to insert a new button with a new image. The sample code looks like this:

' Add button #1
tb.Add 1, "but1" , , 0, 1
' Replace button #1
Tb.Remove 1
Tb.Add 1, "but1" , , 0, 2

A Dlg_ Form

2010-03-26T11:13:00.001+01:00

Any form with a name staring with ‘Dlg_’ follows the dialog rules of GFA-BASIC 32. When a form is created using the Dialog #n command the form automatically gets a name starting with Dlg_0 .. Dlg_31, where 0 <= n <= 31. However, you are not restricted to the Dialog # command to create dialog-forms. Any form, either created at design time using the form-editor or at runtime, can ‘benefit’ from the dialog settings. The only requirement is a name starting with ‘Dlg_’. For instance Dlg_32, Dlg_InputName, Dlg_Msg, etc.

The most obvious change is the adjustment to the DlgBase settings. At the time of creation a form with a name staring with Dlg_ uses the DlgBase settings rather than specified settings. In addition, a Dlg_ form’s keyboard events are handled a bit differently. The PeekEvent command invokes a special GFA-BASIC IsDialogMessage() function to handle the navigation keys (Tab, arrow keys).

I only discovered this recently and didn’t get a chance to figure out how exactly the navigation differs from a normal Form.

Note that in contrast with the remark in the help-file DlgBase Bold has been repaired.

Sleep, DoEvents, PeekEvent, or GetEvent?

2010-03-26T08:15:00.002+01:00

In contrast with VB a GB32 application needs a global message loop to retrieve pending messages from the application’s message queue. In GFA-BASIC 32 the message loop is most often placed in the ‘main’ section of the program and often looks like this:

Do
Sleep
Loop Until Me Is Nothing

Me is a Form object variable holding the current active window of the GFA-BASIC 32 program. The Me variable always represents the current active window should a program open multiple windows. Me always represents a window (Form) unless the last window is closed, then Me is equal to Nothing. That’s the moment the Do loop is ends and the program stops.

GFA-BASIC 32 offers 4 different commands to read the message loop and dispatch the message to the appropriate window procedure. Essentially, all these commands utilize PeekMessage(), TranslateMessage(), and DispatchMessage() - like any other message loop under Windows. They only slightly differ which I will discuss here. Let’s start with PeekEvent because it is the heart of all four commands.

PeekEvent invokes the PeekMessage(V:msg,0,0,0,PM_REMOVE) function, which checks a thread message queue for a message and places the message (if any) in the specified structure. If no messages are available, the return value is zero. The PM_REMOVE flag indicates that messages are removed from the queue after processing by PeekMessage. The following GB32 listing shows pseudo-code for the PeekEvent command.

Procedure PeekEvent()
Dim msg As MESSAGE
// Clear MENU() event array
MemZero(MENU(0), 17)
// Obtain message if available
If PeekMessage(V:msg, 0, 0, 0, PM_REMOVE)
// Copy msg members to MENU() array
MENU(2) = msg.pt.x
MENU(3) = msg.pt.y
MENU(16)= msg.time
// Handle key input messages
If msg.message >= WM_KEYFIRST && _
msg.message <= WM_KEYLAST
// Handle keyboard events at
// the application level.
Exit Sub If Screen_KeyPreview(V:msg)
// If Name starts with 'Dlg_' use
// special IsDialogMessage().
If Me.IsDialog Then
IsDlg_XX_Message(Me.hWnd, V:msg)
Else
~TranslateMessage(V:msg)
EndIf
EndIf
// Send to appropriate window proc
~DispatchMessage(V:msg)
EndIf    // PeekMessage()
EndProc

This pseudo code is rather accurate. I omitted the check for reentrance while executing PeekEvent. Only this, once PeekEvent is executing and is dispatching messages, it cannot be reentered again.

- GetEvent is a simple variation on PeekEvent. Like PeekEvent it only retrieves one message a time and then returns to the application, in fact GetEvent invokes PeekEvent as follows:

Procedure GetEvent()
If Not GetQueueStatus(QS_ALLEVENTS) Then _
~WaitMessage()
@PeekEvent()
EndProc

GetEvent waits for a message when - on entrance - no messages are current in the queue. When a message is available it calls PeekEvent to handle the message and then returns to the application.

-DoEvents is a VB compatible command (used seldom in VB because the message loop is hidden and executed automatically in VB programs). In GB32 it is implement as a loop calling PeekEvent until the message queue is empty.

Function DoEvents%()
Dim Count% = 0
While @PeekEvent()
Count% ++
Wend
~Sleep(Count%)
Return Count%
EndFunc

DoEvents yields execution for a small amount of time after retrieving all messages form the queue. It returns the number of messages obtained. The yielding time depends on the number of handled messages.

- Sleep starts with calling DoEvents. When DoEvents returns 0 then Sleep goes in a wait state and waits for new messages and when they arrive it executes DoEvents again.

Procedure Sleep()
If @DoEvents%() = 0 Then
~WaitMessage()
@DoEvents%()
EndIf
EndProc

Sleep is the preferred command for the main message loop of course.

Kind messages

2010-02-12T10:59:00.001+01:00

Every week I’m happily surprised with a kind message of someone stating his fun with GFA-BASIC 32. Some excerpts:

From a Dutch user:

“Dear Frank, I started my own company in 1982 in plastic things.

After a few years I bought a Atari 520. Later a 1024 and a 20 Mb!! harddisk.

I was interrested and bought a Bookkeeper software thing.

That thing was very slow, so I decided to write my own program.

GFA was the option and what kind of an option !!

I bought the manuals and compiler and didn't sleep many nights because I was concentraded, involved and full power.

I had to develop windows, cursor behavior, and I made myself because of all the stuff a professional bookkeeper.

I've used this program for many years and friends with a own company also, because it was able to do the depreciations automatically.
The taxman never had problems with it. It was clear and understandable.

I've used it until 2001 (with Gemulator) and after that I've sold my company.

Now there are such programs with the same functions of 60Mb, mine (yours) was 93K !!!!

Love you, Henk Reinders (Holland)”

From a German user:

“Hi Sjouke,

I am still alive, no time, hard working. I am now 62 years old and may gain more time for my hobbys in a few years. I started to built up a small homepage for private use only. By the way, I will send you some stuff, step by step, from earlier programming. The prog was coded by my son on a Atari 800XL, we had a lot of fun together with this machine. I presented the gfa32 version to my son on one of his birthdays. It has been very easy to transform the code. All the best for you and all gfa-fans in the future.”

Do you want to share something with the GFA-BASIC community? Leave a comment!

GFA-BASIC Update Build 1166

2010-02-07T12:06:00.000+01:00

The internal linker error caused a "File write error" when creating a stand-alone EXE or a Gfa Editor Extension GLL. The bug occured when one or more $Libraries are linked to the compiled code of the program currently editted. When none of the Lg32 libraries contained subroutines (Sub, Proc, or Func) the linker misses a pointer and reads from address NULL. The entire process of creating the output file is guarded in a Try-Catch exception handler that only reports a "File write error in filename". It doesn't specify what went wrong.
Anyway, this bug is solved in Build 1166, which you can download at http://gfabasic32.googlepages.com/update

Debug.Print to OutputDebugString

2010-02-03T09:46:00.002+01:00

To me the Debug Output Window is the most valuable tool of GFA-BASIC 32. The Debug Output Window is controlled (wrapped) by the COM interface IDebug. I always have the debug output window open just below the main window of the IDE.

There is only one instance of the Debug object (just like Printer, Me, Win_, Dlg_, Error, App, Screen, ClipBoard, Forms, and Code4). It is not up to you to create a Debug object. As soon as you use one of the properties or methods of the Debug object, the GfaWin23.Ocx runtime checks for its existence and creates the thread global object for you.

Both Trace and Print display text in the EDITTEXT control that occupies the client area of the Debug Output Window. The central routine responsible simply sends the WM_SETTEXT message to the control. The subclass procedure of this edit control checks for an overrun of the text limit.

In addition, the central text output routine invokes the OutputDebugString() API with the same text string. The OutputDebugString function sends a string to the debugger for the current application. However, GFA-BASIC 32 doesn’t have a Win32 application debugger as meant in this context. Therefore, if the application has no debugger, the system debugger displays the string. If the application has no debugger and the system debugger is not active, OutputDebugString does nothing.

However, when you are debugging GFA-BASIC 32 in a Win32 debugger (OllyDbg, IDA Pro Disassembler, etc) you’ll see the Debug.Print text in their output windows as well.

ListView Subitems Custom Draw

2010-01-19T12:01:00.003+01:00

Just before Christmas 2009 Peter Heinzig mailed me a copy of his "listView_CellColor" program. He was experimenting with Custom Draw for common controls to provide cell coloring for subitems in a ListView in report-mode. To be honest, I never used custom draw, so I had some catching up to do. After reading the SDK I checked the GB32 disassembly to check if GB32 uses custom draw. Bingo! It does use it with the ListView Ocx control to implement the ListItem's properties ForeColor, BackColor, and Font. Anyone trying to implement custom draw for a ListItem object could get in problems with GB32's implementation, so it is time to implement a custom draw routine for ListView controls taking the GB32 implementation into account.

We step right into the drawing stage of custom draw Ocx controls. I discussed the message handling of custom draw for Ocx controls in a previous entry Custom Draw for Ocx controls. Note this is GFABASIC 32 specific implementation, other languages might use a different method.

Using the correct Ocx type
We left off with the function that invokes a specific subroutine when the NM_CUSTOMDRAW message has come from a ListView, TreeView, ToolBar, or Slider Ocx control. This function, which I called OcxCustomDraw() to emphasize we are processing GB32-Ocx specific custom drawing, passes the general Control variable as the first parameter, by value. In the process of passing, the type of COM variable is changed to the required COM interface.
Note - In VB/GB32 the interface name is the name of a COM object without the leading I. Here we have an Control variable, which is a pointer (4-bytes) addressing the memory occupying a structure for an Control type. When we pass the variable by value, we put the contents of the Control variable on the stack and interpret it in the called subroutine as an address of a (I)ListView type (interface ). Any actions performed on the local Ocx variable will instruct the compiler to use COM syntax for the type (I)ListView. Confusing? Probably worth a new blog entry ...

The drawing process
I'll be short about interpreting the NM_CUSTOMDRAW draw message data passed in the lParam argument. You'll find it in the SDK or MSDN. First we need to cast the pointer in lParam to the custom draw structure for a ListView control.

' ListView custom drawing
Function CustomDrawListView(Lv As ListView _
, lParam%, ByRef retval%, ByRef ValidRet?) As Bool
Dim nmcdr As Pointer NMLVCUSTOMDRAW
Pointer nmcdr = lParam

Now we can access the structure-members using the dot-operator syntax. For a ListView's subitem to draw, we must respond to three draw stages; CDDS_PREPAINT, CDDS_ITEMPREPAINT, and CDDS_ITEMPREPAINT | CDDS_SUBITEM. That is it.

1 CDDS_PREPAINT
Let us start with CDDS_PREPAINT. This notification is sent at the beginning of the drawing of the row. Each row sends it once only. You must response with the correct value to specify what you want next. Well, both GB32 as ourselves want more (sub)item draw messages, so we must respond with CDRF_NOTIFYITEMDRAW. Since GB32 already returns this value, our custom draw function may skip this message (although it wouldn't hurt if you didn't).

Switch nmcdr.nmcd.dwDrawStage
Case CDDS_PREPAINT
'retval = CDRF_NOTIFYITEMDRAW
'ValidRet? = True
Return True

We return from this function with True to let the Form's event sub _MessageProc() know that we handled this message and that it can leave the event sub without further processing.

2 CDDS_ITEMPREPAINT
The next drawing stage is CDDS_ITEMPREPAINT. When GB32 receives this message it fills in the appropriate NMLVCUSTOMDRAW members on return. The common control library than uses the selected colors and fonts for drawing. After it processes this message, GB32 returns with a value indicating it is ready with this list item (row). We trap this message before GB32 handles it an specify that we want additional custom draw messages for each subitem of the row.

Case CDDS_ITEMPREPAINT
retval = CDRF_NOTIFYSUBITEMDRAW
ValidRet? = True
Return True

Because CDDS_ITEMPREPAINT returned CDRF_NOTIFYSUBITEM the common library will start sending notification messages, in the form CDDS_ITEMPREPAINT, before it starts drawing each of the subitems.

3 CDDS_ITEMPREPAINT + CDDS_SUBITEM
To indicate subitem drawing the control library adds CDDS_SUBITEM to the value. So, in the next stage we must process, we must fill in the members of NMLVCUSTOMDRAW that the control library will use to draw. More precisely, we can fill in the .clrText and .clrTextBk fields for the colors and select a new font in the hDC. This is exactly the behavior of GB32. So, we will let GB32 process the message first.

Case CDDS_ITEMPREPAINT | CDDS_SUBITEM
' Set back to the ListView control default colors for each subitem.
nmcdr.clrText   = CLR_NONE
nmcdr.clrTextBk = CLR_NONE

  ' Let GB32 copy the ListItem properties of the row (color _and_ font)
' Go through the ListView window procedure, so forward the WM_NOTIFY message
' (as OCM_NOTIFY) to the ListView's window procedure.
nmcdr.nmcd.dwDrawStage = CDDS_ITEMPREPAINT
retval = SendMessage(Lv.hWnd, WM_NOTIFY + $2000, 0, *nmcdr)
ValidRet? = True

  ' Finally, we get a chance to overrule the color settings:
Local Int Row = nmcdr.nmcd.dwItemSpec + 1   ' 0 to 1 -based
Local Int Column = nmcdr.iSubItem + 1       ' 0 to 1 -based
If lv4_Colors(Row, Column).Fore <> CLR_NONE
nmcdr.clrText = lv4_Colors(Row, Column).Fore
EndIf
If lv4_Colors(Row, Column).Back <> CLR_NONE
nmcdr.clrTextBk = lv4_Colors(Row, Column).Back
EndIf

Return True     ' Notify the Form_MessageProc
EndSwitch  ' dwDrawStage

After overruling the colors the subitem is drawn. Unfortunately, the function uses a global array named lv4_Colors() of type SubItemColors. The following is from the frm1_Load() sub event, lv4 is the Ocx ListView in report mode.

Type SubItemColors
- Int Fore, Back
EndType
Local Int Rows = lv4.ListItems.Count
Local Int Columns = lv4.ColumnHeaders.Count

Global lv4_Colors(Rows, Columns) As SubItemColors

' The array MUST be initialized with the default ListView system colors CLR_NONE (= -1).
' Whenever a subitem cell color must be reset to the default value,
' simply set the Fore and Back members to CLR_NONE.
MemLFill ArrayAddr(lv4_Colors()), ArraySize(lv4_Colors()), CLR_NONE

' Cell (1,1) is left-top-most cell
lv4_Colors(1, 1).Fore = $23FFFF
lv4_Colors(1, 1).Back = $777777
lv4_Colors(2, 1).Fore = $FF
lv4_Colors(2, 1).Back = RGB(0, 255, 0)

The CLR_NONE value indicates the use of the ListView default colors. It is the clue to all drawing.

The integration in GB32 custom drawing might be complicated. If so ask me.

Swap Arrays by ArrPtr()

2010-01-13T17:54:00.001+01:00

Didn't GFABASIC for Atari ST support swapping (or passing) arrays by pointer? I picked up my copy of the book 'GFABASIC' by Frank Ostrowski (1987) to check if I remembered correctly. Indeed, some kind of swapping by pointer is supported. The QuickSort program FO presented on page 22 passes a string array to the sort routine by using *a$(), which is equal to ArrPtr(a$()). To access the array locally in the procedure, the array descriptor passed is swapped with a the descriptor of array a$(). Given a pointer to an array descriptor the Atari ST Swap command supported the following syntax:

Swap *ardescriptor%, a$() ! Atari ST GFABASIC

Unfortunately, the Swap command of GB32 isn't that flexible. The arguments of the Swap command need to be of the same kind. For instance:

Swap a%(), b%()
Swap f#, g#
Swap udt1, udt2

Even a user-defined type can be swapped! Swap works well as long as the data type of both operands is the same. But I have a need to store a pointer (Long Integer) to an array of data and later on use that pointer to access the array's data. So, I want to store an ArrPtr() and swap that pointer with an (empty) array. For instance:

Swap arrdesc%, d() // not supported

After disassembling the code GB32 generates for Swap a(), b() it is easy to see, that GB32 implements the array swap by passing the pointers of the descriptors of these arrays. Internally, a Swap a(), b() is actually a Swap ArrPtr(a()), ArrPtr(b()).

Also, the disassembly reveals the Asm scall name for the library function. Strangely, the name is pgMinBottom, obviously an error in the naming. It is now easy to create a custom routine to swap two arrays by descriptor.

Proc ArrPtrSwap(ArrPtr1%, ArrPtr2%)
  . push [ArrPtr1%], [ArrPtr2%]
  . scall pgMinBottom   ' GB32 naming error
EndProc

Given some arrays, the procedure might be invoked like this:

Dim g%(2), a%(5)
Dim ptrToa% = *a()
Dim ptrTog% = ArrPtr(g())

ArrPtrSwap(ptrToa%, *g%())
ArrPtrSwap *a%(), *g%()
ArrPtrSwap *a%(), ptrTog%

Now you can initialize an array, store a pointer to it in the .WhatsThisHelpID property of an OCX control, and use it later on by swapping it with an empty array. I now can finally conclude my series on custom drawing of single SubItems of a ListView.Listitem object.

The .Tag property

2010-01-11T11:58:00.001+01:00

In COM all strings are UNOCODE BSTRs. GB32 converts a string to UNICODE before it calls the set_Tag() function. When the property .Tag is set with a literal string constant, the compiler optimizes string assignment by converting the literal string to an UNICODE string before hand. For instance, the assignment Ocx.Tag = "Hello" is stored as:

Ocx.Tag = "H" #0 "e" #0 "l" #0 "l" #0 "0" #0 #0

When the .Tag property assignment is actually executed during runtime, the UNICODE string is passed to the set_Tag() function of the Ocx/COM object, and the BSTR is stored with the COM object for later access. But something is breaking the process ...

GB32 stores ANSI code
The rationale behind GB32's implementation of UNICODE vs. ANSI isn't very clear. IMHO the most simple, effective, and fastest procedure would be to store the pointer to the UNICODE string as it is passed to the Tag property. But GB32 converts it (back) to ANSI and stores a pointer to the ANSI-string memory. Of course, GB32 strings might be as large as physical memory and storing a UNICODE string doubles the memory necessary. But that couldn't be the reason for this behavior, could it?

Anyway, so far so good. It is a fact of life. If you like you can store binary data in a string and assign it to a .Tag property. But can you get it out of the Tag property? The answer is No! When the BSTR passed to the set_Tag() function is copied to ANSI, GB32 only stores the pointer to the converted ANSI string (a char* in C/C++). It doesn't save the length of the passed BSTR. So, how does GB32 know how many characters to return from get_Tag()? It doesn't and simply invokes a call to the C-library function strlen(char*), which returns at first occurrence of '\0'.

Binary data cannot be stored in a .Tag property.

The OCX() return type

2010-01-08T10:26:00.001+01:00

What exactly does the OCX() function return? It got me thinking when I was developing the custom draw program. Since GB32 seems to name all COM objects Ocx objects, I expected it to return a general Object type (which isn't exactly wrong). But it doesn't return an Object type. Remember that a DisAsm or Collection COM object aren't created using the Ocx command, but using a New clause in the Dim command. These are not Ocx objects; Ocx objects are COM wrappers for controls only, that is anything with a window handle. Consequently, strictly spoken, the OCX() function returns a Control object.

Any COM type can be cast back to an Object. The only actions performed on an Object are late bound properties and methods. An Object is an IDispatch interface only.
Next in hierarchy is a Control object. It embeds the IUnknown and IDispatch interfaces, but it also includes data for GB32 to maintain the windows/controls. Every Ocx ( = control) includes (embeds) a Control object. Since there is no interface type-info for a Control object (use OleView.exe to inspect COM types), the properties and methods are invoked through IDispatch, like with the Object type.
Finally, there is an interface definition for an Ocx control. The Ocx object is based on the Control object. In addition, each Ocx object has its own control specific data. A Control object is an OCX without the specific control information and without an interface.

Object -> Control -> Ocx
Control = OCX(hWnd)

As you can see, there is nothing wrong to store the return value of OCX() in an Object variable, but strictly speaking it should be a Control type variable.

For a non-Ocx COM object the hierarchy is

Object -> GB32 COM Object type (Collection, DisAsm, etc).

For these types there is no OCX() function (because it depends on a window handle) and should not be cast to a Control object.

Custom Drawing Ocx Controls

2010-01-06T14:48:00.002+01:00

Together with the TreeView common control, the ListView common control is one of the most important control used to present organized data. Since displaying data in columns is probably the most used features of the ListView control, I will discuss how to implement subitem coloring of cells in a report-view mode ListView Ocx control. In this installment I will discuss the necessary steps to start custom drawing a GB32 Ocx control. The ListView cell coloring is discussed in another entry.
Custom drawing
The common control library supports a technique called 'custom draw' to change the appearance of the elements of some of the controls. The custom draw technique was developed to eliminate the need to fully owner-draw entire controls. Custom draw allows trapping only a small set of the drawing operations, rather than perform all the drawing.
The common controls send custom draw messages as a WM_NOTIFY messages to the parent window. The WM_NOTIFY message specifies a pointer to a NMHDR structure in the lParam argument. The NMHDR structure specifies the (notification) code, the window handle and ID of the control from which the message originates.

Type NMHDR
  hwndFrom As Long
  idfrom As Long
  code As Long
End Type

The _MessageProc event
In GB32 a parent-window is usually a Form. The WM_NOTIFY message is a sent message and can only be handled in Form's event sub Form_MessageProc(). The _MessageProc is invoked from inside the Form's window procedure (defined in the GfaWin23.Ocx) before GB32 processes the message itself. The two additional arguments of the _MessageProc (retval% and ValidRet?) determine whether GB32 will actually continue processing this message in its own window procedure once it returned from _MessageProc, which could look like this:

Sub frm1_MessageProc(hWnd%, Mess%, wParam%, _
 lParam%, retval%, ValidRet?)

  Switch Mess
  Case WM_NOTIFY
    ' use Pointer to cast a lParam to a type!
    Dim nmhdr As Pointer NMHDR
    Pointer nmhdr = lParam
    ' Custom draw message.
    If nmhdr.code == NM_CUSTOMDRAW
      ' (do something)
    EndIf
  EndSwitch
EndSub

Noticeable is the elegant way GB32 allows you to cast a pointer to a structure. I explained Pointers in the past.
It is important to realize that NM_CUSTOMDRAW is sent always, for every common control that supports it. As soon as a common control starts it painting process it starts sending this message. It is up to the developer to tell the common control library to send follow-up messages for each stage in the painting process, or to stop sending notifications after the first one arrived. For performance reasons, the library only sends the message that signals the start of the paint-cycle (CDDS_PREPAINT) and then only sends more messages when you respond with a value "send-me-more".
Custom drawing Ocx controls
What to do once you intercepted the NM_CUSTOMDRAW message is described in the MSDN. However, the documentation always discusses C-style handling and provides sample code in case one control wants custom drawing. What if the control is a GB32 Ocx and multiple Ocxs want custom drawing? The question arises how to differentiate between the various Ocx controls when we process NM_CUSTOMDRAW?
Option #1 is to store the window handles of the Ocx-controls in global variables and compare these in a (possibly long) If-Else statement with nmhdr.hwndFrom. Once you find a match you know what to do. This option is certainly valid, but it is not my intention to show you how to solve this problem the API-way, but to show you the GB32- COM way.
The GB32-COM way
This is option #2. We will use nmhdr.hwndFrom to get an Ocx object and then use the object to perform general custom drawing for that object type. Since GB32 supports COM interfaces for ListView, TreeView, ToolBar, and Slider, not all common controls (Header, ToolTip, and ReBar) that support custom drawing can be handled this way. The ReBar common control is not implemented, unfortunately, and Header and ToolTip controls are part of other controls and are not support on their own. So, we need a function that separates the good from the bad.

Function OcxCustomDraw(hWndFrom%, lParam%, _
  ByRef retval%, ByRef ValidRet?) As Bool
  ' Non Ocx controls are rejected immediately, Only OCX() is invoked.

  Dim Ob As Object
  Set Ob = OCX(hWndFrom)

  If IsNothing(Ob)
    Return False        ' Not an OCX control
ElseIf TypeOf(Ob) Is ListView ' Most often used in custom drawing
    Return CustomDrawListView(Ob, lParam%, retval%, ValidRet?)    ' Big chance we have a hit.
  ElseIf TypeOf(Ob) Is TreeView
    Return CustomDrawTreeView(Ob, lParam%, retval%, ValidRet?)
  ElseIf TypeOf(Ob) Is ToolBar
    Return CustomDrawToolBar(Ob, lParam%, retval%, ValidRet?)
  ElseIf TypeOf(Ob) Is Slider
    Return CustomDrawSlider(Ob, lParam%, retval%, ValidRet?)
  EndIf

  ' Not a custom draw Ocx control, 
' continue processing
  ' NM_CUSTOMDRAW in Form_MessageProc()
  Return False
EndFunc

The window handle in nmhdr.hwndFrom identifies the common control, so we pass this value in the first parameter hwndFrom of the OcxCustomDraw() function. The second parameter is the lParam value as it is passed to _MessageProc, holding a pointer to NMHDR. The out-parameters retval% and ValidRet? are passed as well, since they must be set once we processed the message. In addition, we make this a Boolean function to signal the caller (_MessageProc()) to continue processing WM_NOTIFY or to exit the event sub immediately. (The _MessageProc should not perform any action when the message is handled in OcxCustomDraw(), but It might do more processing when the hwndFrom passed in isn't an Ocx object or when NM_CUSTOMDRAW originates from a GB32 Ocx that doesn't support custom drawing. In these cases OcxCustomDraw() returns False.)
To check the Ocx type for a given window handle we need a two step process. First, obtain the address of the object that wraps the control using the OCX(hWnd) function. This is a simple addrObject = GetWindowLong(hWnd, GWL_USERDATA) call. When no object is attached to the window handle Ob Is Nothing and we can skip the rest of the function. When the Ob contains a valid Ocx type we test whether it is of type ListView, TreeView, ToolBar, or Slider using the TypeOf(O) Is Interfacetype construction. When True, we execute either one of four Ocx custom draw operations. These functions are defined as follows:

' ListView custom drawing
Function CustomDrawListView(Lv As ListView _
  , lParam%, ByRef retval%, ByRef ValidRet?) As Bool
  Dim nmcdr As Pointer NMLVCUSTOMDRAW
  Pointer nmcdr = lParam
Return False
EndFunc
' TreeView custom drawing
Function CustomDrawTreeView(Treeview As TreeView, _
  lParam As Long, ByRef retval%, ByRef ValidRet?) As Bool
  Dim nmcdr As Pointer NMTVCUSTOMDRAW
  Pointer nmcdr = lParam
  Return False
EndFunc
' ToolBar custom drawing
Function CustomDrawToolBar(Toolbar As ToolBar, _
  lParam As Long, ByRef retval%, ByRef ValidRet?) As Bool
  Dim nmcdr As Pointer NMTBCUSTOMDRAW
  Pointer nmcdr = lParam
  Return False
EndFunc
' Slider custom drawing
Function CustomDrawSlider(Slider As Slider, _
  lParam As Long, ByRef retval%, ByRef ValidRet?) As Bool
  Dim nmcdr As Pointer NMCUSTOMDRAW
  Pointer nmcdr = lParam
  Return False
EndFunc

For a ListView control Ocx the function calls CustomDrawListView(). When invoking the function the general Ob variable of type Object is cast to a ListView type implicitly. Each of these CustomDrawType() functions casts the Object variable Ob to the appropriate COM type. Inside each function the lParam is cast to the correct API custom-draw structure (see SDK).
Note - The types are all defined in the commctrl.inc.lg32 included in the GB32 package. You can either load this library using $Library or copy-paste the relevant Types.
Final note
The TypeOf(O) Is Interfacetype construction is a library function that checks the object against the IID value of InterfaceType. Therefore it calls the QueryInterface() for that type. This decreases performance of course, although the GB32 implementation of Is TypeOf is pretty fast.
Next time I discuss how to color subitems in report ListView.

Why you should use the latest update

2009-12-08T12:03:00.001+01:00

Bugs and notes come to me by electronic messages. I check them to see if I can reproduce them and if so I make a note to investigate them. Sometimes, the notes lay around my desk for a long time, because 1) I don't have time, or 2) this is more often the reason, the bug is hard to locate. Because of the complexity, after solving I find it sometimes hard to describe the problem and the resolution. You know: "Doctor, when I push here, it hurts there...".

The Vista bug has to do with the memory allocation of the string memory for the Ocx.Name property. When you rename the Ocx (in the Form editor) the memory is released before new (string) memory is allocated to store the new name. GFA bombs! Why? Because GFA mixes memory heaps. The problem is located both in the runtime as in the IDE, but I managed to solve it by a Try/Catch structure in the IDE. For that to happen I had to teach myself code insertion in a binary and writing Try/catch handlers in machine language. Well, its my hobby, so it is no problem, but after so much effort I mostly limit myself to a short note: this bug has been solved. But mostly I give an example in the readme or on my site.

The Double bug is bad! When a string (LPCHR) contains the maximum number of decimal fraction digits in a certain sequence the algorithm FO used is simply wrong. Copy and paste this in your editor:

Const a = -1.79769313486232e+308

Results of floating-point calculations are often stored in strings (for instance a representation in a control). Than used for a calculation the string is converted back using Val or ValDbl. In certain situation this fails and crashes GB, for the exact same reason. The problem: GFA-BASIC uses a general exported DLL function for these conversions (both at editing, compiling and runtime). How do you know when your conversion is wrong or right?? You cannot. Therefore you MUST use the latest update.

Is GFABASIC 32 compatible to GFABASIC 16?

2009-11-13T11:42:00.002+01:00

Yes it is. As a matter of fact I discovered when disassembling the runtime that GFABASIC 32 is much more compatible to GFABASIC 16 than was claimed. The question is; what does compatibility means? Does it mean that GFA-BASIC 16 programs should run without any change? No. Running in a 32-bits environment requires other prerequisites for data handling. An integer is now 32-bits, memory is flat, DLLs have no shared memory, API calls have become obsolete and many new ones are added. So, in this respect any language updated to 32-bits has evolved.

Is GFA-BASIC 32 compatible to the 'On Menu' event handling of GFA-BASIC 32? And compatible to the window and dialog handling? Yes. This is completely implemented, except for 16-bits HandleMessage (if you like to read more about it I might tell you why). There is no holding back for using GetEvent and using Menu(1) !!! It is perfectly well implemented. So, what else do you need?

Modify the Windows style

2009-10-29T10:32:00.002+01:00

For a project I needed to change many window style bits in one session. For this I developed two procedures, one to change the GWL_STYLE and one to change the GWL_EXSTYLE window styles.

$Export
$Export Proc Modify*

Procedure ModifyStyle(hWnd As Handle, lRemove As Long, lAdd As Long)
Local Long Style = GetWindowLong(hWnd, GWL_STYLE)
Style &= ~lRemove
Style |= lAdd
~SetWindowLong(hWnd, GWL_STYLE, Style)
~SetWindowPos(hWnd, 0, 0, 0, 0, 0, SWP_NOZORDER | SWP_NOSIZE | SWP_NOMOVE | SWP_DRAWFRAME)
EndProc

Procedure ModifyExStyle(hWnd As Handle, lRemove As Long, lAdd As Long)
Local Long ExStyle = GetWindowLong(hWnd, GWL_EXSTYLE)
ExStyle &= ~lRemove
ExStyle |= lAdd
~SetWindowLong(hWnd, GWL_EXSTYLE, ExStyle)
~SetWindowPos(hWnd, 0, 0, 0, 0, 0, SWP_NOZORDER | SWP_NOSIZE | SWP_NOMOVE | SWP_DRAWFRAME)
EndProc

As you can see, I collected these in a $Library (.lg32). I'm a big fan of libraries and whenever possible I put general subroutines in a compiled module.

I'm aware of some problems with loading of LG32 files, I had them in the past as well. However, and I don't know why, I don't have them anymore ...

LabelAddr in a GLL

2009-10-26T17:20:00.002+01:00

In two recent posts (here and here) I discussed the problems with subclassing the Gfa_hWnd window in a GLL. In fact, it turned out to be impossible using 'normal' Windows API functions. Another solution was required.
The final solution I developed is based on the MS Detours technique from MS Research Labs. However, not even this highly tricky technique worked for me. The GLL still couldn't be unloaded using the Extension Manager Dialog box. Then, I adapted the Detour technique and configured it in such a way that unloading the GLL isn't a problem anymore. Almost two years ago I first started to study the Detours technique, and finally I came up with a solution to full fill my needs.
The adapted method is based on a GFA-BASIC 32 assembly routine, which is injected into the main window procedure of Gfa_hWnd inside the code of the IDE. To complete my mission I had to figure out the address of a label inside a GFA-BASIC subroutine. The injected code has to jump (jmp) to the label's address. However, the addresses of labels in GLLs (GFA Editor Extensions) are not known in advance.
Both the ProcAddr() and LabelAddr() functions are filled in by the compiler at compile time. In addition, a relocation-table is stored with the compiled program. In contrast with loading an EXE, which is performed by the OS, the addresses in a GLL are relocated by the GFA-BASIC 32 IDE when the GLL is loaded. The IDE is capable of adjusting the ProcAddr addresses inside the GLL, but it doesn't adjust the hardcoded LabelAddr values.
It takes a trick to obtain the relocated address of a label. The GLL is loaded into memory and addresses are calculated using an offset. When we know the offset value the hardcoded label addresses can be calculated. The function Gfa_LabelOffset in the next code, does just this. Since the value is constant for the entire GLL, it is stored in a static variable.

Function Gfa_LabelOffset() As Long
Static LabelOffset% = 0
If LabelOffset% == 0
GetRegs : 1
LabelOffset% = _EIP - LabelAddr(1)
EndIf
Return LabelOffset%
EndFunc

The function can be used to obtain the real location of a label as follows:

Local stubAddr% = LabelAddr(stub) + Gfa_LabelOffset
stub:

The LabelAddr(stub) returns the hardcoded value set by the compiler. The real location is then adjusted by the offset value used to relocate all addresses in the GLL.

EXE behaves different

2009-10-20T10:38:00.002+02:00

"My program runs fine in the IDE, but it freezes when the compiled EXE is started." What is happening?
In the past ten years this message pops-up once and a while. At the same time this message is never repeated. The developer reviews his or her program and recognizes a programming bug. Then after the bug is solved, the program runs without any problem. Until now I never (!) encountered a compiler bug that resulted in an erroneous EXE.
Then, how is it possible that the EXE behaves different than the IDE-program? Some things to consider.

The most logical error is a programming error (90% chance).
I noticed a problem in user-defined types, for instance a member array isn't properly dimensioned, or a Boolean member is used (see the Help File for notes on using Booleans in a Type). Check your Types, but even better review the initialization code of your program.
In Mysterious Errors I described a theory about errors that cannot be reproduced. But again, the programmer is to blame.
The compiler inserts Trace-code between each code line in the IDE. You can disable this with $StepOff and get the same compiler result as an EXE.
An EXE might behave different because the Compiler setting Full Branch Optimization for EXE is enabled. This is the only option that produces a different result. (1% chance).
Make sure you are aware of the ByRef Bug for Sub procedures. Insert ByVal and ByRef in the procedure headings. Better: use Sub only for event subs.

All in all, look for the problem in your code, not in the compiler. If an EXE works with one OS, but doesn't with another, than we have a possible bug!

Difference between _Message and _MessageProc

2009-10-14T17:27:00.006+02:00

There are two somewhat strange, certainly badly documented, event subs for forms: the Form_Message and Form_MessageProc event. Although they sound much alike, they are quite different. Both events are invoked from inside the window procedure of the form. However _Message() is called only for a handful of messages, but _MessageProc() is called for all messages, regardless of their origin. These subs are defined as:

Sub frm1_Message(hWnd%, Mess%, wParam%, lParam%)

Sub frm1_MessageProc(hWnd%, Mess%, wParam%, 
  lParam%, retval%, ValidRet?)

The _MessageProc event sub With the _MessageProc Sub you can actually filter or influence the behavior of the GB32 window procedure for the Form window class. The _MessageProc is called before GB32 handles the message itself (more or less, maybe later more on this). The sub obtains six message parameters. The first four are the same as defined for a Windows API window procedure. Every message, whether it is obtained from the message queue (the posted messages) or by a direct call from any other source (for instance through SendMessage), is handled in the window procedure. The hWnd parameter is the window to which the message is sent (we already know the objects name: frm and we could obtain the window handle from the object, that would have lowered the number of parameters by one). The Msg parameter is the message number—which is usually a constant such as WM_ACTIVATEAPP or WM_PAINT. The wParam and lParam parameters differ for each message, as does the return value; you must look up the specific message to see what they mean. Often, wParam or the return value is ignored, but not always. The _MessageProc() event sub has two additional parameters (ByRef) that allow you to return a value. For instance, when you want GB32 not to handle a certain message you can set the ValidRet? Boolean variable to True and provide a return value by setting RetVal%. What value RetVal must have is defined in the Windows API SDK. It often says something like: "If you handle this message return zero (or..)". Now let us look at an example. Suppose you want to store the window coordinates of OpenW #1 in the register so the application can use these values to open at the same place. In GB32 you must then handle the sub events Form_ReSize and Form_Moved to store the coordinates. As an alternative you could use Form_MessageProc and handle the WM_EXITSIZEMOVE message as follows:

Sub Win_1_MessageProc(hWnd%, Mess%, wParam%, _

      lParam%, Retval%, ValidRet?)

 Local Int x, y, w, h

 Switch Mess

 Case WM_EXITSIZEMOVE

   GetWinRect hwnd, x, y, w, h

   SaveSetting "MyComp", "ThisApp", "Position",

        Mkl$(x, y, w, h)

   ValiRet? = True : RetVal = 0

 EndSwitch

EndSub

Note the Form_MessageProc() actually _is_ the subclass window procedure for the GB32 windows (Form, Dialog, OpenW, ChildW, ParentW). Subclassing is a built-in feature of GFA-BASIC 32. As such the the OCX control Form is perfectly suited to write custom controls.

The _Message event sub The Form_Message is different: you cannot filter messages and return values, you can only respond to a handful of messages, to WM_SIZE, or WM_PAINT for instance. Why these? Because these are posted messages, messages that are retrieved from the message queue. Note that most posted messages have a accompanying sub event. For instance, a WM_SIZE message results in calling the Form_ReSize event sub. You can use the _Message sub to handle many messages that are otherwise handled in these event subs. All you need to know is which messages are posted. These are all input messages like key and mouse messages, window management messages like moved, sized and wm_paint. You must then, just as in _MessageProc, create a Switch/Case structure to respond to the message. The main disadvantage is that you must interpret the wParam and lParam parameters yourself... The order in which the sub events are called You can easily test in which order the sub events are called. For posted messages, those that are retrieved from the message queue using Sleep, the _Message() event is called before any other sub. Then the message is 'dispatched' to the window procedure and the _MessageProc is called. And at last, the event sub is invoked. For a WM_SIZE message the sequence is: Win_1_Message() Win_1_MessageProc()

Win_1_ReSize (This article was previously posted on the GFA-BASIC Google Pages. It has been edited to remove errors.)

The Sub-ByRef flaw

2009-10-14T17:02:00.001+02:00

A call to a Sub procedure using by reference arguments might not update the correct variable. To understand this behavior be sure to understand the differences between ByVal and ByRef arguments. This is explained in the next tip 'Passing values ByRef or ByVal'. Here you have learned that a Sub by default takes arguments as ByRef, making ByRef optional. Unfortunately this is not always true.

When an argument is passed by reference, the procedure is passed the address of the argument variable. When the argument is a global variable the address of the variable is passed as expected. In the following situation the ByRef clause is omitted and the global variable is updated to 100 correctly.

Global a% = 50
MySub(a%)
Print a% ' 100
Sub MySub(b%)
b% = 100
EndSub

When a second Sub is called from within MySub passing b% by reference, b% is not updated as expected. The variable b% is passed by value, rather than by reference!

Sub MySub(b%)
b% = 100 : NextSub(b%) : Print b% // still 100
EndSub
Sub NextSub(c%)
c% = 200 // unexpected: c% is ByVal argument
EndSub

Why this is happening is unclear, but it is easily repaired by using ByRef explicitly in Sub headings.

Sub NextSub(ByRef c%)

Loading a library: fail or success?

2009-10-14T16:59:00.001+02:00

When the $Library directive is parsed (triggered when the line is changed) the specified library is loaded and the exported items are added to the Imports tab in the sidebar. When the file is indeed located and opened a message of success is written to Debug Output Window saying "Loading lg32filename".
Any errors caused by the $Library are then due to a corrupt lg32 file.

The "Load lg32 error" message
Programs that contain references to libraries using the $Library directive may occasionally show a "Load lg32 error: filename.lg32" in the status bar. This message is generated when the specified library can't be located at the specified path or, when a path is omitted, in the current active directory, 'My Documents\lg32', or in directories that are searched using the SearchPath API function.
This message should therefore be called: "Lg32 file not found".

Reload project to reset current directory
When a lg32 can't be found the most obvious reason is an unexpected active directory. Sometimes when working at a project the active directory is changed and the project's directory isn't the current any longer. To check for this, simply reload the project, because this sets the current active directory back to the project's folder.

Set default path for Libraries
An undocumented feature is the possibility to set a default path for libraries in the registry. The registry key HKEY_CURRENT_USER\Software\GFA\Basic must contain the key "lg32Path" specifying the default path for the libraries. The key is not present at default, so you must add the key yourself.

Hooking to handle Gfa_hWnd messages?

2009-10-07T17:33:00.001+02:00

In the Why you cannot subclass Gfa_hWnd I explained why the Gfa_hWnd cannot be subclassed to extend the editor's functionality.

Still, I need to intercept and modify messages for the main IDE window Gfa_hWnd. Some kind of subclassing is required. The other feature Windows offers is the 'hooking', known as Windows Hooks. "Hooking is a sort of subclassing, only it isn't associated with a single window, but with a thread or even the whole system. It's a kind of filter of Windows' messages that allow you to override, or add functionalities when a particular message is received." Sounds promising, doesn't it?

Hooking Example

In fact, I did create a test program. First, two hooks are installed, the WH_GETMESSAGE and the WH_CALLWNDPROC hooks. There are other hooks, but these seem to be the most logical ones. Just to show how hooking might be done in GFA-BASIC 32, I present some code.
After declaring two global Handle variables, the hooks are initialized as follows:

Global Handle hGetMsgHook, hCallWndHook
' Process or modify all messages (of any type) for the system whenever a
' GetMessage or a PeekMessage function is called (WH_GETMESSAGE).
hGetMsgHook = SetWindowsHookEx(WH_GETMESSAGE , ProcAddr( GetMsgProc), App.hInstance, GetCurrentThreadId())

' Process or modify all messages (of any type) whenever a SendMessage
' function is called (WH_CALLWNDPROC).
hCallWndHook = SetWindowsHookEx(WH_CALLWNDPROC , ProcAddr( CallWndProc), App.hInstance, GetCurrentThreadId())

From this code you can see that both hooks are thread wide, meaning all messages for the thread are passed on to the hook filter functions GetMsgProc() and CallWndProc(). This is one of the reasons I didn't use the hook technique to 'subclass' the Gfa_hWnd window. Later more.
The application defined hook filter functions are defined as:

' WH_GETMESSAGE Hook
Function GetMsgProc(ByVal idHook As Long, ByVal wParam As Long, ByVal lParam As Long) As Long
  Dim msg As Pointer MSG
  Pointer(msg) = lParam
  If msg.hwnd == GfahWnd && msg.mess > 0 && msg.mess <> 275
    Trace msg.mess
  EndIf
  Return CallNextHookEx(hGetMsgHook, idHook, wParam, lParam)
End Function
'
' WH_CALLWNDPROC Hook
Function CallWndProc(ByVal idHook As Long, ByVal wParam As Long, ByVal lParam As Long) As Long
  Dim msg As Pointer MSG
  Pointer(msg) = lParam
  If msg.hwnd == GfahWnd && msg.mess > 0 && msg.mess <> 275
    Trace msg.mess
  EndIf
  Return CallNextHookEx(hGetMsgHook, idHook, wParam, lParam)
End Function

The GfahWnd variable contains the Gfa_hWnd value and MSG is an API user-defined type to store the message parameters. All well known I presume.

Is hooking a solution?
Does Windows Hooking offer a solution to my problem? The answer is no. Subclassing goes further than hooking. Subclassing functions can return values in response to messages, hooking filter functions cannot. Another issue is the use of thread wide filter functions, that are called for every message that is sent through SendMessage or retrieved with GetMessage. Not only do these hook functions significantly drain on system performance, they might also interfere with the application at hand, that is, the program currently being developed and run in the IDE.

I need another solution.

Why you cannot subclass Gfa_hWnd

2009-10-05T11:31:00.002+02:00

In the course of interpreting the disassembly of both the GfaWin32.exe and the run-time I created quite some editor extension procedures. Most of them are rudimentary and should be developed further, but some of them are very useful (at least to me). I always hoped to put them together in one single GLL file and make that GLL available. However, I never came to do that. I had a problem I didn't understand, and thus didn't know how to solve. After unloading that GLL the IDE crashed.

To add new functionality a Windows developer will most likely start by subclassing the window. In fact, subclassing is the most elementary of all modification techniques. I started by subclassing both IDE windows, the main IDE window Gfa_hWnd and the editor window Gfa_hWndEd. The subclassing was performed in the Gfa_Init() procedure and undone in Gfa_Exit(), which seemed logical at the time. However, as said, this caused a (fatal) problem that at that time I couldn't resolve and I reserved it for a later moment to handle. I was convinced it was something I simply overlooked and at that stage it wasn't really an obstacle. The GLL was automatically loaded when the IDE was started and unloaded when it was closed. I never unloaded the GLL by hand using the Editor Extension Manager dialog box.

Sometimes I was annoyed by the problem and tried to find out the cause of it. It turned out that when the GLL was unloaded in the course of closing the IDE, the un-subclassing was performed after the main window was closed. So, the Gfa_hWnd window didn't exist anymore and re-installing the old window procedure didn't cause any problem. But, when I unloaded the GLL when the IDE was active, using the Extension dialog box, it always crashed the IDE. The undoing of the subclassing of Gfa_hWnd was the problem. In fact, you cannot subclass the Gfa_hWnd in a GLL.

My problem was that I didn't understand exactly what I was doing when I was subclassing a window. Let me illustrate by describing the path a WM_COMMAND (a posted) message follows to where it gets actually handled. Here is what happens when you select the GFA-BASIC 32's Editor Extension Manager dialog box, either from the menu-bar or through a shortcut First the OS puts a WM_COMMAND message in the application queue. The program obtains the message in an endless GetMessage loop and dispatches the message to the window procedure (note: the one I tried to subclass). The window procedure invokes the modal dialog box and a new message loop is started to handle the dialog box. Now, after subclassing, the OS invokes the new window procedure rather than the old one, and requires the new procedure to execute the old window procedure using the CallWindowProc() API. So, the old window procedure, which handled the WM_COMMAND, is called from the new window procedure located in the GLL. In fact, when the dialog box is put on the screen and a modal message loop is started, the program is still executing the new window procedure inside the GLL! After closing the dialog box the program will want to return to the location it was called from, the place where CallWindowProc() API was invoked. You see the problem now?

The old window procedure was invoked from inside the new window procedure (located in the GLL), which was just unloaded using the Editor Extension Manager dialog box. There is no place to return to! Ergo, the most elementary technique, subclassing a window to add new functionality, is not possible for Gfa_hWnd in an editor extension.

Don't use Mul Command

2009-09-09T10:47:00.002+02:00

Sometimes a compiler bug pops up. Here is one: the integer math command Mul int, const is buggy! So don't use it. For instance:

Mul j%, 2

Replace it with a mathematical instruction like:

j% = j% *2

or use the function variant:

j% = Mul(j%,2)

This bug is reported when j% is a ByRef parameter of a subroutine. I verified it and it is a bug indeed. I'm not aware of problems in other situation.

Obtaining the name of the actual procedure (2)

2009-08-18T11:15:00.001+02:00

Does a compiled GFA-BASIC 32 application contain debug information? I got interested and disassembled a compiled (EXE) GFA-BASIC 32 application.

I immediately noted why Avira anti-virus complained about compiled GFA-BASIC 32 programs in the past. The GFA-BASIC 32 EXE application start-up code is quite different from ‘normal’ C/C++, VB, and Pascal applications. In fact, there is no such start-up code! The compiled program immediately calls the exported DLL function ‘GfaWin23_5()’ from the GfaWin23.Ocx runtime. The DLL function calculates the start-address of the main program part and executes it. The entire program is executed from inside the GfaWin23_5() function which contains all start-up and program-exit instructions.

My main concern was ‘how is the stack frame of a compiled procedure initialized?’ More on stack frames see http://gfabasic32.blogspot.com/2009/08/obtaining-name-of-actual-procedure.html.

It turns out that the runtime DLL contains two additional INITPROC() functions; I called them INITPROC_EXE() because the call to INITPROC() in the debug version has been replaced to a call to a EXE specific initialization procedure. It still creates a stack frame, but it is a bit smaller because it lacks debug information. In addition, the EXE doesn’t contain symbol information whatsoever. There is no way an EXE can return information about symbols; procedure and variable names and their locations.

Obtaining the name of the actual procedure

2009-08-15T11:58:00.001+02:00

Obtaining information about a currently executing procedure is only possible when the program is running in the IDE. One of the main differences of the debug-version and the stand-alone version (EXE) is the storage of debug information. Sounds logical, doesn't it?

To get a program compiled, the compiler collects all identifiers (procedure names, global and local variables, labels, etc.). The compiler creates memory locations for the variables and compiles source code to object code (machine code instructions). Each procedure gets its own portion of memory whose starting addresses are stored in a table. After compilation the procedure and function calls are corrected to make sure they call the correct object code addresses. After the compiler finishes the connection between an identifier-name and its location is broken. The call to a subroutine in the source code is replaced by a call to a memory address. A reference to a variable is replaced by a reference to a memory location. The compiler creates machine language instructions and uses hardcoded memory locations. There is no room for the original name of the identifiers, be it subroutine names or variable names.

However, when a program is compiled inside the IDE (F5) the compiler inserts debug information. How exactly the compiler handles this process I don't know. I do know however, that each subroutine (non-Naked) calls the INITPROC() library routine inside the GfaWin23.Ocx. This library function creates a stack frame for the subroutine. Each function has a stack frame and most compilers create them the similar. Usually you'll find these instructions to create a stack frame:

push ebp

mov ebp, esp

The INITPROC() function installs a much larger stack frame. The first 96 bytes are used to store an extended exception record to make sure local variables are cleared properly in case of a problem. In GFA-BASIC 32 the use of structural exception handling (SEH) is similar as in C/C++. The SEH-technique allows to store more information than C/C++ does. GFA-BASIC 32 cleverly uses this freedom to store additional debug information. One of the members of the stack frame contains a 'pointer' to the procedure information that is stored in a table by the compiler. The compiler doesn't delete this (hash) table after it has finished compiling. The GFA-BASIC 32 debug commands get there information from this stack frame member and essentially they use one function to process this stack frame member: CallTree(). CallTree figures out the stack frame of the current subroutine and it is able to figure out the extended stack frames of subroutines that called the subroutine. (It uses the SEH-list to do this.)

The first entry of the string that CallTree returns is the procedure that is currently executing. The name of the actual procedure is obtained by invoking:

Print CallTree(1)

but it only works in the IDE.

After a good holiday

2009-08-14T10:13:00.001+02:00

I hope you had a good holiday, we had. We rented a house at the border of a fjord in Norway, got ourselves a small boat and went out fishing everyday. We definitely want to get a small “hytte” over there.

During the holidays I got some mail at gfabasic32@gmail.com. Some were personal opinions about GFA-BASIC in general and some about GFA-BASIC 32 specifically. Mostly I reply these messages as soon as possible, but sometimes I save them for further examination. In general everybody gets a reply. If you didn’t got one yet, please repost your message.

A new season, a new start. Hope to post more blog entries this season.

Mysterious errors

2009-06-27T17:45:00.003+02:00

I'm puzzled by a few serious but not reproducible errors. The first one occurred many years ago and had to do with the collection of variables during compiling. Another bug occurred in compiling GLLs where the compiler complained about not being able to open the file to save the GLL. Again, another bug complained not being able to initialize a Hash table in a GLL. However, the bug didn't present itself each time the GLL was started. Then there is the bug where a subroutine call in a 22000 line program wouldn't compile because of a variable collection/initialization error. Why aren't these bugs reported more often? They seem to come up only occasionally. I'm starting to think the problem is related to thread-safety errors. The compiler intensively uses functions from the runtime GfaWin23.Ocx, especially the Hash functions. Everything the compiler collects, names, types, data, etc is stored in Hash tables. The Hash tables are actually pointers to a structure with pointers to allocated memory. There is a pointer to an array of strings containing the hash key name, a pointer to an array of data, an array of indices mapping the key to an index, and some more. To create a Hash table the runtime DLL must support thread safety, because another process/thread can not interfere with the allocation of a Hash table. I am not able to conclude that the Ocx is fully thread-safe in this respect. I have seen a lot of thread-protection functions in the runtime disassembly, but they are mostly string related. The Hash functions on the other hand don't provide a locking mechanism. The documentation (Multithread.pdf) states that GFA-BASIC 32 is not completely "reentrant". However which functions suffer from the lack of reentrancy isn't reported. Since these bugs only occur occasionally I wonder if this has to do with two or more threads executing a runtime function the same time. For instance, I believe the Val() function isn't thread-safe (I'm not sure, because it is hard to tell). But what if two processes or threads were calling it the same time? In the early days of the Microsoft C run-time library, math routines were nonnreentrant aswell, and accordingly did not save and restore the registers used on the 80x87 floating-point coprocessor. Why wouldn't GFA-BASIC 32 suffer the same? It didn't get tested that well. Maybe somebody may recognize these contemplations and may tell us about it.

Patching the GfaWin23.Ocx DLL

2009-06-18T12:07:00.004+02:00

It is not a good idea to patch the GfaWin23.Ocx DLL. For instance, recently someone wanted to use the properties and methods of GFA-BASIC's RichEdit Ocx for the newer RichEdit control version 4.0 from MsftEdit.DLL. To accomplish this task the runtime DLL was patched by replacing some ASCII text using a HEX-file-editor. However the GfaWIn23.Ocx is updated regularly and patching each new update isn't an ideal solution to add new features to the BASIC. This got me thinking about adding new functionality to the runtime. In case of the newer RichEdit control I considered three options.

1 Use the WrapRichEd command

Consider the purpose of the patch. By forcing GFA-BASIC 32 to load a different richedit DLL and changing the class name used to create the RichEdit Ocx control, GFA-BASIC 32 will create the newer control when it invokes the statement Ocx RichEdit. Then, the properties and methods of the RichEdit COM interface can be used to manage the control. (Note most properties and methods are simply wrappers for the SendMessage(hwndEd, EM_xxx, wParam, lParam) function. These wrapper functions use an internal structure with state information GFA-BASIC uses to optimize the performance of the COM functions.)

Ok, back in 1999 the first GFA-BASIC 32 beta didn't contain the Ocx command. To wrap a control up in a COM interface GFA-BASIC 32 support(ed) the WrapCtrlName statements, like WrapRichEd. This command assigns a COM interface to a child control. The child control might have been created using a GFA-BASIC control command, like the general Control creation command, or simply by using an API function like CreateWindowEx(). You can still find examples of the use of the Wrap-commands in the \Samples directory. In general it is used as follows:

Dim rtb1 As RichEdit
RichEditCtrl "", 101, x, y, w, h
WrapRichEd 101, V:rtb1, "rtb1"

This encapsulates a RichEdit control with ID = 101 in an Ocx variable rtb1 and sets it event name to "rtb1".

Back to the issue at hand. The window class name of the newer RichEdit control is "RICHEDIT50W'. The current implementation of the Ocx RichEdit (or RichEditCtrl) statement is to load RichEd32.DLL and to create a control with the classname "RichEdit20A". To get a new control we need to load the MsftEdit.DLL first and then create a control of this class using the general command Control. Like this

Global Handle hMsftEdit = LoadLibrary("msftedit.dll")
Assert hMsftEdit
Global Dim rtb As RichEdit
Control "", 3, "RichEdit50w", WS_BORDER, 100, 70, 100, 284
WrapRichEd 3, V:rtb, "rtbev"

The Ocx is now accessible by its variable name rtb and the event subs have the format Sub rtbev_Event(). Great!? Well, this process continues to work until you invoke a window-style property for the RichEdit Ocx, like rtb.BorderStyle=. In this case the control is destroyed and recreated, a process completely hidden for the developer. When the richedit control is recreated, the 'normal' GFA-BASIC 32 DLL code for the creation of a RichEdit Ocx is invoked, which then creates a "RichEdit20A" class control. Implicitly, the version 4.0 richedit control is destroyed and a richedit control of an older version is created. (The properties that cause a recreation of the RichEdit control are .HideSelection, .MultiLine, .ScrollBars, .BorderStyle, .TabStop ). Unless you give up these properties, this doesn't seem an ideal technique.

2 Poke the DLL (Advanced)

Under conditions this is a valid way to go. Only the loaded DLL is affected. The code is modified at runtime, for instance in the initialization process of your program. Such a modification isn't permanent, once your program has finished, the DLL is unloaded and the next time the original GfaWin23.Ocx is loaded again. When you insist on patching the DLL poking at runtime is definitely worth a shot. The API functions to use are VirtualProtextEx() and WriteProcessMemory(). VirtualProtextEx() is required before poking, because in this particular case the data section – which is read-only - of the DLL has to be patched.

In general you can use the addresses as they are showed in a HEX-file editor and poke those addresses. However, the system doesn't guarantee that a DLL is loaded at the preferred base address. In case multiple DLLs require the same base-address Windows may relocate one of the DLLs giving it a new address in (virtual) memory. You can invoke an additional LoadLibray("GfaWin23.Ocx") or GetModuleHandle() to obtain the base-address, of course you must decrement the DLL count immediately by invoking FreeLibrary(). Maybe I come back on this in some other post.

3 Send messages on your own (Preferred method)

When a GFA-BASIC 32 program requires a new or custom control it should proceed the API way. Point. Load the DLL and create a control using Control or CreateWindowEx(). Then send messages to manage the control and use the parent form's _Message sub event to respond to WM_COMMAND messages. When the custom control sends WM_NOTIFY messages use _MessageProc. More on _Message(Proc) see http://gfabasic32.googlepages.com/faqforms

To utilize GFA-BASIC 32 to the most, you can write wrapper functions and put them in a $Library. Most C/C++ include files for custom controls also present C/C++ macros that invoke the SendMessage() API to manage the custom control. You can easily convert them to Function calls and put them in a library.

Update: Build 1165

2009-05-25T10:13:00.004+02:00

Recently I uploaded a new update of GFA-BASIC 32 to http://GFABASIC32.googlepages.com/. The update includes both the GfaWin32.exe, the IDE, and the runtime GfaWin23.Ocx. Both got build number 1165, which you can check from within the Explorer (right-click), and for the runtime by using DllVersion$. For instance: Trace DllVersion$ ' "2.30 Build 1165" Debugging takes time It has been a while since the last update, but I had to do a lot of disassembling. Well, not exactly the disassembling-process itself because that task is performed by a program, but the interpretation of the disassembly. To be able to understand and interpret a disassembly you need to be able to guess what is going on so that you can recognize patterns. To understand the editor part of the disassembly you need to know how an editor is programmed, to understand a DLL-disassembly you are required to have knowledge of DLL programming, etc. Also, to understand the implementation of the COM controls (OCX), you are required to understand the concept of COM and how to develop OCX controls. So, each time I start interpreting a new part of the disassembly I must study the concepts of that particular issue before I can actually begin. To get acquainted with new information some time may pass.

Urgency due to Val-bug But it is time for an update now. The update contains things I have done in the past year, but it got some urgency due to the Val() bug. This bug was first reported in 2001, but I never got to it.

What is going on? A string having 15 digits and starting with the digits "281479…." was converted to the floating-point value 402…. The position of the decimal point and whether the value is positive or negative isn't important. The function responsible for the conversion isn't only invoked by Val() or ValDbl(), but is heavily used by the IDE (both editor and compiler) as well. I'm pretty sure I located the bug and solved it. I'm also pretty sure the string must fulfill the conditions mentioned to get wrongly converted. However, the chance that the string fulfills the first condition (having 15 digits) is rather big, because the floating-point conversion function Str$() often returns a string with 15 digits when the number of digits in the fractional part is indefinitely. However the number must actually start with the mentioned digits to return a wrong value. Over the years the problems with Val() are reported on a regular basis, so this situation occurs. Reason enough to update.

Atari ST RIP

2009-05-14T11:51:00.002+02:00

It has been a while since my last posting. For one a ST->GFA32 porting project came across which turned out to be not portable after all. It gave me an opportunity to actually use an Atari ST again, put a floppy disk in its built-in disk at the side and listen to those cranky noises when it loads. Wow, I actually thought I missed it, but I didn't. In my mind those Atari ST days have became more romanced than they were. The magic of the Atari ST lies in its innovative OS (GEM), but the innovation was magic because this was never seen before in those days.

The Atari 1040ST still stands next to me and each time I enter my room and I look at it, I don't long for those days anymore. The last years I seriously concerned buying an old Atari ST for the sake of old times. However, now it is here, my memories have vanished and are replaced by those that made me take the step to MS-DOS and Windows. The only thing that remains are the heartbeats I recall having when I first got GFA-BASIC to work and produced my first GEM program. I think these beats were the loudest ever heard as a result of a piece of software I created. That must explain romancing the Atari ST. For me, the most valuable lesson learned is to let the Atari ST rest in peace.

The Command.Picture property

2009-04-22T15:33:00.005+02:00

Years ago I asked a question on the GFA MailingList about the .Picture property of the Command Ocx. At design-time the button displays the bitmaps of an ImageList properly, but when the program was run the pictures were showed with a black background. I forgot about it for years, but recently I created a program with buttons (Command Ocx) with images and the problem reappeared. The image assigned to the button was definitely a masked-bitmap, without the transparent color applied. The difference with all those years back ant the present time, is the amount of documentation and interpretation of the dissassembly of the GfaWin23.Ocx. I immediately started a debugsession to see what happened when a iml.ListImages(idx).Picture is assigned to a Command Ocx. The session turned out surprisingly informative, neither the Command nor the ImageList Ocx contained a bug. I was thinking wrongly, I used the wrong ListImage method, I should have used iml.ListImages(idx).ExtractIcon. To begin with, the ImageList control was assigned a bitmap. However the control stores the single images in two separate bitmaps, a mask bitmap and a masked bitmap (because I had set the ImageList.UseMaskColor property). The background color of the bitmap image was blacked out (which I specified using the ImageList.MaskColor property.) I then invoked the following command to give the button a picture, assuming this would provide the Command Ocx with the original image I put into the ImageList control:

cmd.Picture = ImageListToolbar.ListImages(61).Picture

But I assumed wrongly. The .Picture property of the ImageList returned the handle of the masked bitmap only. So, to give a Command Ocx a transparent image from a ImageList Ocx use the .ExtractIcon method.

cmd.Picture = ImageListToolbar.ListImages(61).ExtractIcon

The Command.Picture = pict pseudo-implementation is (without error and IsNothing checks) as follows: type = pict.get_Type handle = pict.get_Handle SendMessage(Command.hWnd, BM_SETIMAGE, (type=1? IMAGE_BITMAP: IMAGE_ICON), handle) Giving the Command.Picture property a Picture object containing an icon will result in a transparent image in a Button control.

ANSI API functions and RichEdit

2009-04-08T11:30:00.005+02:00

Recently someone patched the GfaWin23.Ocx DLL by replacing the "RichEd20.dll" text entry by "MsftEdit.dll" and "RichEdit20A" by "RICHEDIT50W". The patch isn't very difficult since both text entries are equally sized. The patch was made to obtain the functionallity of the RichEdit Control version 4.0 (which for some reason is called 50) by the GFA-BASIC 32 Ocx interface. By pathing the Ocx file this way, he succeeded in using the "msftEdit.dll. So far so good, but the patch raised a question for me. Why would this control only register a "RICHEDIT50W" class and not a "RICHEDIT50A" ANSI variant? What effect would that have on GFA-BASIC 32 using ANSI functions only?

Previous RichEdit control versions (3.0, 2.0) support two window classes "RichEdit20A" for ANSI systems and "RichEdit20W" for UNICODE systems. When you were compiling a program (in C/C++) for a UNICODE program you would use the "RichEdit20W" class in the CreateWindowExW() API function. GFA-BASIC 32 uses the "RichEdit20A" window class to create a RichEdit Ocx using CreateWindowExA. The properties and methods of the RichEdit Ocx are implemented by sending control messages using SendMessageA().

After patching the rich edit control is created by invoking CreateWindowExA and passing a pointer to an ANSI string containing "RICHEDIT50W". How can that work? The new control only supports wide character coding, how can it accept an ANSI string? I think I found the answer. ANSI API functions are redirected to the wide (UNICODE) variant.

When a program is specifically created as a UNICODE application (which is possible only for NT 4.0 and higher) it uses the UNICODE versions of the system API functions. All API functions have an ANSI and a UNICODE variant with different(!) entry points in the system DLLs. For instance, the SendMessage() API comes in two variants: SendMessageA() and SendMessageW(), two different functions. The xW() system functions expect strings formatted in UNICODE format. On UNICODE Windows systems (thus everything above Windows 95/98/Me) the ANSI versions of the API functions first translate a string parameter to UNICODE and then call the xW() version passing the newly created UNICODE string. This makes ANSI programs quite slow when API functions use strings (upto 3 times, see "Under the Hood 1997" by Matt Pietrek).

GFA-BASIC 32 is an ANSI program and invokes only the xA() versions of the Windows API. Therefor, on Windows NT 4 and above any string passed is converted to UNICODE before handled in the xW() version of the function. (GFA-BASIC 32 is not prepared for pure UNICODE systems, it had to run on Winddows 95 as well.) Back to the question, why does the MsftEdit.Dll accept an ANSI string in CreateWindowExA()?Because in turn the CreateWindowExA() calls CreateWindowExW() on any 'not Win95/98/Me' system passing the classname "RICHEDIT50W" as a UNICODE string. This means, according to my findings that the MsftEdit.dll won't run under Windows 95 when used from the patched GFA-BASIC 32 Ocx-dll. These Windows systems don't redirect to a wide version of the API function.

BTW It might be useful to know how GFA-BASIC loads the appropriate richedit dll. Just before a RichEdit Ocx control is created, GFA-BASIC 32 loads the appropriate library, as follows: If hLibRichEd == 0 hLibRichEd = LoadLibraryA("RichEd20.dll") If hLibRichEd == 0 hLibRichEd = LoadLibraryA("RichEd32.dll") If hLibRichEd == 0 Then RaiseErr "OutOfMemory" Endif Endif Then "RichEdit20A" is used in a CreateWindowExA() API call to create a control window of the this class.

GetFirstVisible method not implemented

2009-04-04T12:14:00.005+02:00

The ListView Ocx method .GetFirstVisible isn't implemented and simply returns Null. It is described as "to return a reference to the first ListItem object visible in the internal area of a ListView control". I think FO simply forgot to implement it properly, because many properties and methods return a reference to a Listitem object and a copy/paste action of the relevant GfaOcx23 source code would have sufficed to make the method work. Pitty. However, by using two (not VB-compatible) ListView methods the problem is easily solved. (Actually, it is one property and one method) ListView.TopIndex ListView.ListItem(index%) The ListView.TopIndex get-property returns the index (long integer) of the first visible item. It doesn't return a reference to a ListItem, but returns a long starting with 0. The ListItem(index%) returns a reference to a ListItem object from an index starting with 1. Yes, that is COM combined with Windows API. Anyway to replace the .GetFirstVisible method you should use:

Local ListItem li
// Set li = ListView.GetFirstVisible replacement:
Set li = ListView.ListItem(ListView.TopIndex + 1)

Pointer and Gfa_Var object

2009-04-03T10:22:00.006+02:00

I wasn't finished discussing the Pointer [To] data type. Maybe I should summarize the things I figured out until now:

GFA-BASIC 32 is capable of generating two types of code to access data; directly and indirectly using C-like pointer code.
A Pointer [To] type variable is 32-bits variable without a VarPtr address. The data memory address is set using Pointer=. Other than this, GFA-BASIC 32 treats the pointer as a normal data type.
All ByRef subroutine arguments are Pointer To variables, whose VarPtr-address is set by the caller (instruction that executes the subroutine).

Because of the duality, GFA-BASIC 32 needs to handle a Pointer To variable differently from normal variables. A normal variable has a name and memory location, in fact the variable-name is an alias for a data location. As such a variable name is not known after compiling, all references to the variable name are removed and replaced by assembler instruction theat memory loaction. Therefor a normal variable has only one 'address', either returned by VarPtr (V:) or ArrPtr. A Pointer (32-bits wide) on the other hand is split in two separate units. The address the pointer is stored and the VarPtr address it is pointing to. A Pointer variable has two addresses. This is refelected in the Gfa_Var object. A Gfa_Var object is an item of Gfa_Vars collection, a collection of variables of a certain subroutine. The Gfa_Var has two properties that illustrate this concept:

Gfa_Var.VarPtr Gfa_Var.Addr

In case of a normal variable both properties return the VarPtr address, In case of a pointer the .Addr property returns the address of the Pointer variable and the .VarPtr property the address set using Pointer()=. To help investigate I wrote a small procedure to show the Gfa_Var properties in the Debug Output window. A call to ShowVar is done by including a copy of a Gfa_Vars collection item. In case of the example below, I inspected a global user-defined-type declared as Foo. To obtain a collection of global variables you either use Gfa_Globals or Gfa_Vars(""). To inspect a local variable, execute ShowVar from inside a procedure and use Gfa_Vars0!varname.

ShowVar Gfa_Vars("")!Foo, V:foo, ArrPtr(foo), _
 "- Global Foo As Tfoo:"

Proc ShowVar(vGfaVar As Gfa_Var, vp%, ap%, comment$)
  Debug comment$

  Debug "Variable: "#39 & vGfaVar.Name & #39 & _
    ", TypeName: "#39 & vGfaVar.TypeName & #39 & _
    ", Sub: "#39 & vGfaVar.PName & #39
  Trace Hex(vGfaVar.Type)
  Trace vGfaVar.Addr
  Debug "ArrPtr(" & vGfaVar.Name & ") = " ap
  Debug "VarPtr(" & vGfaVar.Name & ") = " vp
  Trace vGfaVar.VarPtr
  Trace vGfaVar.Size
  Trace vGfaVar.Len
  Trace vGfaVar.IsTyped
  Debug
EndProc

ByRef parameters are Pointers

2009-03-31T17:03:00.009+02:00

Yes, that is right. A ByRef parameter is effectively a Pointer [To]. Let's see what this means. A pointer variable of some data type behaves exactly as a variable instance of that type. A variable pdbl declared As Pointer To Double behaves exactly as a Double. Not only is it used in the same way as a normal instance of a Double, but anything GFA-BASIC 32 allows to be done with a Double data type is allowed with pdbl (a pointer to double). Once a pointer has been initialized (given a memory address) the compiler interpretates the pdbl pointer variable as a variable of type Double. For the programmer the pdbl is the same as a normal Double variable. The compiler on the other hand accepts pdbl as a Double on each occasion it processes it, but it generates different code to perform operations on pdbl. The problem is that the compiler isn't aware of the exact location of pdbl's data location. Variables that are instantiated using Global, Local, Static, and of course Dim, are included in the program (exe). They have a reserved portion of memory that the compiler know about. All code generated by the compiler can operate on this memory location directly. The assembler code generated for accessing 'normal' variables is therefore quite different than assembler code generated for pointers. For pointers GFA-BASIC 32 generates C-like pointer code; it stores an address (data location) in a register and uses this value to indirectly access the data location. When the GFA-BASIC 32 compiler parses the code, it marks all un-addressed variables before generating code and when it comes to create assembler instructions it generates pointer code, assuming the actual address will be known at runtime. There are only two type of variables the memory address isn't known from at compile time: Pointer To and ByRef. Investigation showed that both types are marked the same way when they are encountered during compiling. A ByRef procedure argument is in essence a Pointer To variable. Initializing a pointer The pointer pdbl can be initialized at runtime only. The pointer pdbl initially points to address 0 (null). To be used practically, the pointer variable must be assigned a memory address. The compiler uses this memory address to operate on. Normally, the memory address of GFA-BASIC 32 variables is 'handled' through the VarPtr function (or its shortcut V:). Essentially, a pointer lacks a 'VarPtr' address. (It could have been an idea when GFA-BASIC supported a 'VarPtr(var)=addr' command to set the memory address. However, in case of variables that use a descriptor (String, arrays) there would also have to be an 'ArrPtr()= addr' to set the memory address for such a pointer.) To initialise a pointer a new keyword was introduced: Pointer(pvar)=. (Note - This still requires the programmer to be aware what memory to set with Pointer(). A Pointer To String will require a pointer to the descriptor of another string!) I discussed this command multiple times and won't go into that here. The question is how is the apllicable on ByRef arguments? A ByRef variable is a Pointer To variable and there is only one way to set the VarPtr address of a variable: the Pointer()= command. This command is implicitly invoked when a variable is passed to a procedure taking a ByRef argument. To get access to the passed argument the compiler generates code apropriate for the data type, but the memory address of the actual data isn't known at compile time. The ByRef variable is a local variable on the stack without a VarPtr address. The compiler than generates pointer-operation-code to process this ByRef variable, exactly the same code as generated for a Pointer To variable. This is in contrast with a ByVal variable. Here the compiler generates code to operate on the variable's memory directly, because its memory address is known in advance. (A local variable is located relative to the stack entry point (esp) of a procedure. The stack pointer is copied to ebx which is used by the compiler to locate the local variables. A local variable is recognizable in assembler instructions like mov eax, 112[ebx]. ). So, for the compiler the ByVal and ByRef keywords have two different meanings. It tells the compiler how to pass the argument to the subroutine and determines the type of code to generate. This is VERY important to realize when you are dealing with pointers in general. In case of low-level programming you must realize what exactly you are receiving in your subroutine. You need to ask yourself whether you need pointer code or normal code to be generated for that variable. Remember the ListView custom sort soutine I presented earlier? Windows passes the lParam member of the LV_ITEM structure to the compare function, which holds a pointer to a ListItem COM object. Do you remember to function's prototype? Here its is.

Function CompareDates(ByVal lngParam1 As ListItem,
  ByVal lngParam2 As ListItem, ByVal iCol As Long) As Long

Why does it need to be declared as ByVal, rather than as ByRef? Because it isn't all that simple (understatement). Some data types force GFA-BASIC 32 to generate pointer code by default, these include user-defined-types (Type) and Ocx/COM objects. GFA-BASIC 32 generates pointer-to code for the ListItem COM object by default. When the parameter would be declared ByRef, the value passed by Windows would force GFA-BASIC to generate code that uses lngParam as a pointer to a Listitem pointer. Hence Excpetion Errors! Ok enough for now, but its not end!

Pointers are pointers indeed!

2009-03-31T11:10:00.004+02:00

I discussed the Pointer [To] data type in an article published at the GFA=BASIC 32 site: http://gfabasic32.googlepages.com/thepointertodatatype. It is actually quite accurate ;-). However, I needed to re-investigate the Pointer data type, because I got some unexpected 'Unexpected Exceptions'. I had to extend the investigations by studying disassemblies and the Gfa_Var object. I also had to reset my knowledge entirely and start from scratch all over again. In the article I published I focussed on comparing a Pointer To to a normal data type. I tried to proof that a Pointer data type isn't so different from a normal variable. Although, I am correct in this article I missed an important aspect of pointers. I simply didn't realize that GFA-BASIC 32 handles a Pointer data type differently, and I didn't realize it because I didn't inspect the resulting code generated by the compiler. Actually, the first lines of the first article signal the problem: "Pointer is a data type to declare variables as pointers.", and then the syntax is given as: Dim p As [Register] Pointer [To] type p: pointer variable type: any data type (Int, String, Double, user-defined-type) This declaration is complete but not accurate enough, because a pointer to an Ocx object is allowed too. In fact, you may declare a pointer to anything that GFA-BASIC 32 considers a data type. And this might proof to be very important, because GFA-BASIC 32 considers something to be a data type when it is an element of the internal TypeInfo hash table containing data types. How these data types are added to this hash table, GFA doesn't care! For instance, when you load a $Library, the data types from the lg32 are appended to this hash table, and the same is true when GFA-BASIC 32 starts and initializes all primary data types (Int, Bool, String, Hash, Variant, etc, etc.), they are simply added to the hash table. (Since I'm trying to implement the Class data type, this information is essential. GFA-BASIC doesn't care about a type as long as it is in the 'TypeInfo' hash table. We'll see where this will go.) Ok, back to the problem. In the declaration it is explicitly stated that a pointer can be located in a register, see the optional Register keyword. This actually indicates a different treatment of a pointer variable! A variable of type Double (8-bytes) cannot be located in a register, because a register is only 32-bits (4-bytes) wide. It is beyond this post how GFA stores (local) variables relative to the ebx register and reserves edi and esi for Register variables. Maybe in a later post; it isn't relevant to the topic at hand. What is important, is that GFA indeed handles a pointer type different, it handles a Pointer variable indeed as 32-bits pointer, otherwise you couldn't store a pointer (to any type) in a 32-bits register, would you? Wow. How did I miss this? Well, I'm only human too, you know. All I did was investigate the information GFA-BASIC 32 returned from a (pointer) variable using GFA functions like TypeName, VarPtr, and ArrPtr. I only wanted to know how the returned information differed form a normal variable compared to a pointer variable. As I pointed out in the article, the only difference seems to be the lack of a memory location for the data for a variable. Of course, this is true, but GFA-BASIC also generates different code to access the data of a pointer variable. Since I didn't inspect the disassembly (DisAsm Ocx object) I didn't see it. As it turned out, GFA-BASIC uses the C pointer-style to access a memory location through a pointer; the GFA-BASIC pointer type is compatible with the C-pointer. Since I will try to keep this post not too technical, I will limit the assembly code a minimum. Important to relaize is that a pointer can be kept in a 32-bit register, which doesn't apply for variables wider than 32-bits. Unfortunately, the compiler won't accept the statement:

Local p1 As Register Pointer To Double      ' double *p1;

The syntax control accepts it, but the compiler doesn't put p1 in a register. Schade (unfortunately). On the other hand the speed increase would be minimal, it is the difference of using a register directly: mov dpt [esi], value ; set first long pointed to in esi and of first copying the pointer to eax from the its (stack) position: mov eax, dpt 116[ebx] ; move pointer content mov dpt [eax], value ; set first long to value GFA also optimizes te code by keeping the pointer in eax when the pointer is accessed multiple times in a row (see for yourself). Now we are where I want it to be. The compiler generates assembler code to access the data of a variable declared with Pointer [To] through a pointer, like C. For instance the second long eax points to is accessed using mov dpt 4[eax], value ; set second long And this is completely different from the code used to access a non-pointer variable. As a conclusion I will summarize how to treat a pointer in GFA compared to C:

' Declare and initialize a double
Dim dbl As Double = 3.1         ' double dbl = 3.1;

' Declare an unitialized pointer to double
Dim p As Pointer To Double      ' double *p;

' Initialize the pointer
Pointer(p) = V:dbl                ' p = &dbl;

' Assign a value to dbl through p:
p = 7.2                           ' *p = 7.2

In the next post I discuss the ByRef and Pointer commands.

Sort a ListView Ocx

2009-03-30T12:07:00.004+02:00

To set the scene you might want to look at the knowledge base about sorting a ListView control in (Visual) BASIC http://support.microsoft.com/kb/170884. GFA-BASIC 32 supports only one method to sort a column, where VB uses three (!) properties to get a ListView control sorted. The .Sort method is defined as: ListView.Sort column%, compare% The .Sort method of the control only sorts the items alphabetically, either ascending or descending. The column% argument specifies the column to sort, but in contrast with the ColumnHeaders collection it starts counting at 0, rather than at 1. I have no idea why, but the column% parameter is passed to the LVM_SORT message directly. Ok, well so be it. The compare% argument is a bit more complex, because it is used as a bit flag. When the lowest bit of the high order word is set ($10000), the column is sorted descending (Z-A), otherwise ascending (A-Z). The low-word of the compare% argument specifies the compare mode GFA-BASIC 32 will use when comparing one item to another. The values are the same as for Mode Compare. For example, to sort the second column in a descending way using uppercase comparison (Mode Compare = -2), you would use: ListView.Sort 1, $10000 Or (-2) A bit complicated. Maybe the Sort method should have used the Mode Compare setting rather than letting it be specified in an argument. Anyway, a column may be sorted comparing using lowercase or using uppercase separately from the global setting. Custom Sort A column doesn't always consist of text string entries that have to sort alphabetically. A column may consist of dates or numbers (integers or floats). The .Sort method isn't prepared for sorting anything different than text. The link to the knowledge base opens an article that discusses how to create a custom sort for dates for a VB ListView control. Although, GFA-BASIC 32 tries to be VB compatible, the ListView Ocx control differs in many aspects. (The previous post discusses how the ListItems collection differs from VB.) GFA-BASIC 32 stores a pointer to the ListItem object in the lParam member of the LV_ITEM structure when it adds an item to the ListView Ocx. VB stores the ListView's item index. This difference is important because of the custom compare function to write for the custom sort. To initiate a custom sort you must send the LVM_SORT message to the ListView. Most often you will do this after a click in the column header. In GFA-BASIC 32 you might see the following code, ported from the code presented in the MS knowledge base article:

' GFA32 argument ByRef, not by value!
Sub ListView1_ColumnClick(ColumnHeader As ColumnHeader)
  Dim lngItem As Long
  ' Note:
  ' ColumnHeaders collection is 1-based
  ' ListItem.SubItems(iCol) is 0-based
  ' ListView.Sort iCol is 0-based

  Dim iSubItem As Long = ColumnHeader.Index - 1 ' 1-based

  'Handle User click on column header
  If ColumnHeader.Text = "Name" Then  'User clicked on Name header
    'ListView1.Sorted = True        'Use default sorting to sort the
    'ListView1.SortKey = 0          'items in the list
    ListView1.Sort iSubItem, 0          ' 0-based
  Else
    'ListView1.Sorted = False       'User clicked on the Date header
    'Use our sort routine to sort by date
    SendMessage ListView1.hWnd, LVM_SORTITEMS, iSubItem, ProcAddr(CompareDates)
  End If

  'Refresh the ListView before writing the data
  ListView1.Refresh

  ' MS/VB
  'Loop through the items in the List to print them out in sorted order.
  'NOTE: You are looping through the ListView control because when
  'sorting by date the ListItems collection won't be sorted.

  For lngItem = 1 To ListView1.ListItems.Count
    'ListView_GetListItem lngItem, ListView1.hWnd, strName, dDate
    'Print ListView1.ListItems(lngItem).AllText
  Next

  ' GFA32 - The ListItems collection is sorted as well.
  Dim li As ListItem
  For Each li In ListView1.ListItems
    Print li.AllText
  Next

End Sub

To show the differences with VB the code is heavily commented. The clue is located in the next code line:

SendMessage ListView1.hWnd, LVM_SORTITEMS, iSubItem, ProcAddr(CompareDates)

The .hWnd property returns the window handle of the ListView Ocx. The wParam argument specifies the corrected column number and the lParam argument holds the pointer to the function to compare two ListView items. The CompareDates function is declared as:

Function CompareDates(ByVal lngParam1 As ListItem, _
  ByVal lngParam2 As ListItem, ByVal iCol As Long) As Long

The first two long integer arguments receive the lParam member of the LV_ITEM structure, which is in GFA-BASIC 32 a pointer to a ListItem object. The compare function is a callback function. It is called from inside Windows and never from a GFA-BASIC 32 statement. GFA-BASIC 32 cannot check the function parameters against the data types passed when called. When the program is executing the lParam members are simply copied to the first arguments of the compare function. Because we know the value points to a ListItem object, we cast the 32-bits value to a Listitem. The GFA-BASIC 32 compare function is much simpler, convert the text of the ListItems to apropriate data type and compare:

Function CompareDates(ByVal lngParam1 As ListItem, _
  ByVal lngParam2 As ListItem, ByVal iCol As Long) As Long

  Dim dDate1 As Date, dDate2 As Date

  ' MS/VB way:
  'Obtain the item names and dates corresponding to the
  'input parameters
  °ListView_GetItemData lngParam1, hWnd, strName1, dDate1
  °ListView_GetItemData lngParam2, hWnd, strName2, dDate2

  ' GFA32 way. The LV_ITEM.lParam is passed to the compare
  ' function. The lParam contains the address of the ListItem
  ' object, which we intelligently casted to a ListItem object!
  dDate1 = ValDate(lngParam1.SubItems(iCol))
  dDate2 = ValDate(lngParam2.SubItems(iCol))

  'Compare the dates
  'Return 0 ==> Less Than
  '       1 ==> Equal
  '       2 ==> Greater Than

  If dDate1 < dDate2 Then
    CompareDates = 0
  ElseIf dDate1 = dDate2 Then
    CompareDates = 1
  Else
    CompareDates = 2
  End If

End Function

The ListItems Collection (1)

2009-03-28T09:06:00.007+01:00

Recent posts discuss the underlying implementation of the Collection Ocx object. I pointed out that COM (read Microsoft) dictates the properties and methods and the number and type of parameters used to invoke them. In short, a collection is a COM object with a limit set of prededicated members, where the member type is a Variant. In the same style VB/COM introduced collections to provide as a means to access items of a control. In early Windows only the standard controls ListBox and ComboBox provided a user interface to access an item from a list of strings. For these controls COM/VB doesn't provide a collection to set and get a given item. Both COM controls included the following properties and methods to manage the entries in the control: .AddItem .RemoveItem .List(index) .ListCount Knowing everything about the Collection object now, you will immediately see the resemblence with the Collection objects properties and methods: .Add .Remove .Item(index) .Count When it came to create COM wrappers for the common controls introduced with Windows 95 like ListView, TreeView, ToolBar, StatusBar, and ImageList, the VB creators thought about abstracting the items of a control by introducing Collections. The elements of these controls were now to be accessed like the mother of all collections, the Collection object. Whenever a control hasn't a fixed number of elements it's elements are to be managed by a collection. For a ListView control this meant the introduction of multiple collections to manage the different aspects of the control. For instance, when the ListView is viewed in report or detail view it contains a header control, which required a ColumnHeaders collection. Then there were the items of ListView itself, they were assembled in a ListItems collection. Then there were checked and selected items, they were collected in a CheckedItems and a SelectedItems collection, respectively. Fortunately, the collections ListItems, CheckedItems and SelectedItems are all collections of the same (data) type: the ListItem object. This brings us to the subject of this post. The ListItems collection is a collection of ListItem objects. As any collection it supports - as it should - the well known Collection properties and methods to manage the entries. The ListItems collection is a way to access the ListView items, which are more than simple strings. A ListView item must specify text, an icon, a selected icon, a checked state, a selected state, etc. The windows API describes a ListView item in a LV_ITEM structure (Type). Type LV_ITEM mask As Long iItem As Long iSubItem As Long State As Long stateMask As Long pszText As Long cchTextMax As Long iImage As Long lParam As Long iIndent As Long End Type This API type is connected to the ListItem COM object. Note that ListItems is a collection of objects of this ListItem object. Anything you do using a ListItems collection (Add, Remove, Count, Item) means operating on a ListItem object. For instance, the .Item method returns a ListItem object, and the .Count property returns the current number of ListItem objects. For now and the upcomming post it is important to realize a few things.

A ListItem object is directly connected to a LV_ITEM structure. A pointer to the ListItem Ocx object, as it is implemented by GFA-BASIC 32, is stored in the lParam parameter of the LV_ITEM structure.
When you add an item to the ListView, a ListItem COM object is created and a pointer is stored in the LV_ITEM structure. Then the LV_ITEM is inserted into the ListView control. The ListItem is NOT added to som internal array of ListItems, because GFA-BASIC doesn't maintain a hash table for the ListItems collections.
A ListItems collection object only provides a way to access these items. A ListItems collection is used to count the number of items in a ListView and to obtain and remove a single ListItem object. When you invoke the .Remove method of the ListItems collection the ListView's item is removed and the ListItem COM object stored in the lParam is destroyed.

The ListItems collectection complies to the interface of a Collection Ocx, but it isn't (at all) implemented as a Collection Ocx, as I described in previous posts. There is no underlying hash table where the ListItem objects are stored. The ListItems properties and methods act upon the ListView directly. When ListItems.Count is invoked, the COM object sends the LVM_GETCOUNT message to the ListView control. In the same way, the .Item(index) method of the ListItems collection, sends the LVM_GETITEM and obtains the ListItem object from the lParam member of the LV_ITEM structure. When you use the For Each construct to iterate over the ListView's items, GFA-BASIC sends a LVM_GETITEM for each item currently present in the ListView. As such, the ListItems collection always represent the current state (and thus sort order) of the ListView. This is an important difference with VB, where the ListItems collection is stored separatly (in a hashtable) from the ListView's items. VB must take extra steps to keep the ListItems collection in sync with the actual state of the ListView. A strange design flaw, because after a sort operation VB's ListItems collection is completely out of sync! Next post discusses a custom sort routine for a ListView.

The Form_Load event

2009-03-18T09:35:00.001+01:00

Remember the previous mail about the _KeyUp event resulting from the F5 keypress to run the program? To get rid of the pending WM_KEYUP from F5 you could put a DoEvents statement as the first line in your program when it uses the LoadForm command. But how does this interfere with the form's _Load event? First, give the next code sample a look. DoEvents // discard WM_KEYUP LoadForm frm1 // invokes frm1_Load Do : Sleep : Until Me Is Nothing Sub frm1_Load EndSub The _Load event is not invoked from within the message loop. Instead the sub frm1_Load is called as the last thing in the LoadForm command. The _Load event isn't like other event subs that result from some notification message from Windows. COM, and thus GFA-BASIC 32, defines a whole set of standard events (mouse, key, and focus events) for windowed Ocx controls. Windowless Ocx controls (ImageList and CommDlg) on the other hand cannot receive input messages and don't support these events. Where do the event calls come from? The standard Ocx event subs are invoked from within a subclassed window procedure. When an Ocx is created it is immediately subclassed and prepared to invoke the event subs. Windows controls typically send certain window messages to their parent window. Some of these messages, such as WM_COMMAND and WM_NOTIFY, provide notification of an action by the user. Others, such as WM_CTLCOLOR, are used to obtain information from the parent window. Rather than handling these messages, the parent (or container in COM terminology) intercepts certain window messages and sends them back to the control. The control, in its subclassed window procedure, can then process these reflected messages by taking actions appropriate for an ActiveX control (which is, firing an event) or setting a color. Fired events mostly originate from a real Windows message, but not always. The Form's _Load event is one of them, it is an event invoked from within the LoadForm command. There are no WM_PAINT, WM_ACTIVATE, or WM_NCACTIVATE messages pending to be fired as an event. The message queue is empty. Filling in the form wit data is to be done in the _Load event.

API	Meaning	ImageList property
cx	Define the width and height, in pixels, of each image.	.ImageWidth
cy	Defines the height of each image	.ImageHeight
flags	Set of bit flags that specify the type of image list to create. - use a mask (ILC_MASK) - color depth (ILC_COLORnn)	.ColorFormat (sets color depth and sets ILC_MASK)
cInitial	Specify the number of images that the image list initially contains.	1 - Determined by GB32
cGrow	Number of images by which the image list can grow when the system needs to make room for new images.	1, 2, or 4 - Determined by GB32