30 July 2015

Tip: How to create short jmp

When doing some assembler I noticed an important optimization setting for jumps. To force the compiler to generate short jumps (short jmp, short jz, short jnz) the Branch optimization setting must be >= 1.


A short jump requires 2 bytes of opcode instructions. Otherwise a jump takes 6 bytes. Short jumps are only generates when the target is within 127 bytes offset, of course.

27 June 2014

Passing default ByRef parameters to a Sub, a flaw?

In my opinion the GFA-BASIC’s Sub procedure type is an anomaly. When possible you should use Procedure instead. Oh, and when you are too lazy to type Procedure than just use its abbreviation Proc. A Procedure takes all arguments by value by default and is completely backwards compatible to previous GFA-BASIC versions.

On the other hand, if you are stubborn enough and want to use Sub anyway, make sure you use ByRef and ByVal explicitly with all parameters. Do not expect the default ByRef passing will work, because it won’t. We discussed this earlier in The Sub-ByRef flaw. This posting ended with the quote “Why this is happening is unclear, but it is easily repaired by using ByRef explicitly in Sub headings.” I was never convinced this was a real bug and I always assumed a reasonable explanation would come up some day. And it did ….

VB is the flaw; ByRef turns into ByVal
Let us consider the default Sub by reference implementation in VB, VBA, and VBScript. An argument is passed by reference only when the caller uses a very specific syntax. Only when the program executes the subroutine without parentheses the sub gets a reference to the actual argument. When the programmer puts the arguments between parentheses the arguments are passed by value. The next sample demonstrates how and when VB(A/Script) executes the default:

' Normal VB call of a Sub
' passing a reference to Hello$
SPrintStr Hello$ Sub SPrintStr(sArg As String)

When VB encounters a call with arguments inside parentheses, the arguments are evaluated first. In other words, before something is put on the stack the expression inside the parentheses is evaluated (executed, calculated, etc) and a local copy of the variable is assigned the outcome of the evaluation. The local copy is passed by reference to the subroutine, which than becomes a by value passing of the original parameter. Using the parentheses-syntax in the next example will pass the address of a local variable to the Sub SPrintStr.

' VB call of a Sub using ()
’ making and passing a copy of Hello$
Sub SPrintStr(sArg As String)

Conclusion VB
When VB calls the subroutine with parentheses the sub gets a reference to a copy of the argument and the default ByRef situation suddenly turns into a ByVal passing. The VB Sub and its implicit, default, by reference passing introduces performance loss and unnecessary memory consumption! Remember this when you port VB code to GB32.

You’ll find the whole story on http://blogs.msdn.com/b/ericlippert/archive/2003/09/15/52996.aspx

GFA-BASIC supports with parentheses
You can almost feel the agony FO must have felt when he found out about this VB quirk. How to maintain backward compatibility to previous GFA-BASIC versions and VB? In GB we are used to place parameters between parentheses. Should we suffer from this VB anomaly as well? Either way, FO decided to support the Sub implementation with parentheses only. Passing arguments without parentheses is equal to passing them with parentheses.

Although the Sub-ByRef problem is much clearer now, the GB32 implementation is still a bit ambiguous. Because GB32 mimics the call with parentheses only the subroutine always receives a by-value argument to a default ByRef parameter. You may omit the parentheses in GB32, but it still executes the version with parentheses. Only when a global variable is passed to a default by reference argument the actual variable address is put on the stack.

Conclusion GB32
Despite the ambiguity between global and local parameters, you should, as a general rule, no longer consider a default by reference parameter as [in/out] when you omit ByRef in a Sub declaration. Inside the Sub you don’t know if you are dealing with the actual variable [in/out] or with a copy [in]. Always use ByVal and ByRef explicitly in a Sub declaration.

31 May 2014

Problem with local Hash variables

GB32 does not support the destruction of local Hash variables. This is by design. Global Hash variables are released when the program terminates. This does not mean you can’t use local Hash variables, you just have to add the termination code yourself.

This behavior might be the cause of many reported memory leaking problems.

Let us look at some examples. First suppose you have a subroutine like this where a local hash variable is used to store the results of the Split regular expression command:

Proc Split_Local(ByRef t$, sep$)
  ' Declare a local Hash variable.
  Dim hs As Hash String

  ' Split creates a new hash table of String,
and destroys the hash allocated memory first. Split hs[] = t$, sep$ ' Explicitly erase Hash variable, because ' memory allocated by hs[] is not destroyed ' automatically when going out of scope. Hash Erase hs[] EndProc

The Dim command declares a Hash String variable hs. The variable is put on the stack. Stack memory is temporary space limited to the scope of the procedure call. A hash variable occupies 8 bytes divided in two Long types. The first Long is a pointer to heap memory. This pointer is set to the hash-table descriptor once a value is added to the table. Initially, the pointer is Null. The second Long contains the code for type of data the hash is going to store. Here the type indicates a String, so the hash is used to store String values.
When the hash variable goes out of scope, at the end of the procedure, the stack is cleared or reset to the value it was at the point where the procedure started executing. The 8 bytes reserved for the hash variable are simply discarded without freeing allocated memory first.
A hash table allocates memory dynamically. When the hash needs more memory, it is allocated automatically. The hash grows and shrinks automatically allocating and freeing heap memory on demand. When the hash variable goes out of scope the allocated memory is no longer referenced by any GB variable or GB garbage collector. This memory gets freed after the application has ended and all of the application’s memory is released to the OS.

  • A local hash variable must be freed explicitly using Hash Erase on the variable name.

The Split command clears the Hash table as well, that is when the first Long of the hash variable isn’t Null. Before Split starts splitting the string in to tokens that are to be stored in the Hash String variable, it completely erases the Hash. In fact, the Split command invokes the runtime function HASHERASE, which is also called with the Hash Erase command.

Static Hash
Now suppose you would like to use Static on a local hash variable. That would prevent unnecessary memory de-allocations in your procedure and would improve performance when the procedure is executed, wouldn’t it? Wrong. Look at the next example:

Proc Split_Static(ByRef t$, sep$)
  ' Static declares a global Hash variable
  ' with local scope.
  Static hs As Hash String
  Split hs[] = t$, sep$, 10

Although the hash variable is declared local, a Static variable is actually a global variable. They are treated the same as other global variables, only their visibility is limited to the procedure they are declared.

Note When asked for the variable address using VarPtr(hs) the address returned is located in the global data section of the program. VarPtr() does not return a stack address, the Static variable is not stored in the stack. For the duration of the program execution the static/global hash variable hs[] can not be changed by other code than the procedure it is declared in. Because a static variable is assigned to the program’s data section, the GB32 application will release the memory it allocated. The static hs[] variable is destroyed when the application quits. When a program is executed from within the IDE all globals will be destroyed and so will be the static hs[] hash variable.

Let us consider the example where the static/global hash variable is passed to Split. Upon entry Split will destroy any entries the hash variable references, the hash variable is destroyed. Than, a new hash table is allocated and its new pointer is stored in VarPtr(hs) + 0. The contents of  VarPtr(hs) + 4 remains unchanged, because it specifies the hash data type. When Split finishes the global/static variable hs[] points to a new hash table. Access to the elements in hs[] is now limited to the code between the Split command and EndProc. Since the hash isn’t destroyed when the procedure returns, the program now carries with it allocated memory that cannot be accessed until the next time the procedure is called. And when the procedure is executed the Split command immediately destroys the hash table. Instead, you could insert a Hash Erase at the end of the procedure, but what does that give you? A local hash variable that is stored as a global variable.

If you like to read more on hash variable, go to Passing a hash variable to a subroutine

More on local scope
Automatic destruction of variables with local scope is only supported for String, Variant, Object,  BSTR and arrays. When a local array is used the compiler inserts a call to CLEARARR(). The code responsible for clearing other type of local variables – a function called CLEARMULTI located in the runtime GfaWin23.Ocx – accepts a Long integer (4-bytes) where each byte contains the number of local variables of one specific type. The Long is coded like this: BBVVOOSS. The Lo byte contains the number of String variables to clean and the high byte of the lo-word contains the number COM objects to release. The hi-word contains the number of Variants and BSTR types.

Yes BSTR types. Unfortunately GB does not provide a data type BSTR we can use to store UNICODE strings. However, all COM objects that require a string use BSTR as a parameter type. When the compiler creates code to invoke a method or property taking a COM string as an argument, the ANSI string is converted to a BSTR before the method or property is called. When necessary the BSTR is stored in a hidden local variable and should later be destroyed.

02 December 2013

Using methods and properties through IDispatch

This is all about two – more or less – undocumented features; the GFA-BASIC _DispID() function and a special dot-curly operator, the .{dispID} syntax.

An object’s layout in memory is, when using a BASIC Object variable data type:

MemObj vtable (array of function pointers)
AddrOf vtable AddrOf QueryInterface()
RefCount% AddrOf AddRef()
…. AddrOf Release()
…. AddrOf GetTypeInfoCount()
… data AddrOf GetTypeInfo()
  AddrOf GetIDsOfNames()
  AddrOf Invoke()
  AddrOf ComPropertyMethod1()
  AddrOf ComPropertyMethod2()

After the following commands the BASIC Object variable oIE holds a reference to an instance of Internet Explorer, an automation server and therefor guaranteed to support a dual interface.

Dim oIE As Object
Set oIE = CreateObject("InternetExplorer.Application")
Trace Hex(Long{V:oIE})
Set oIE = Nothing

An Object variable is actually an Int32 data type and holds the address returned by CreateObject.
Initially, the Object variable is zero (or Null) and is interpreted as Nothing. The following statement does nothing more then checking if the variable oIE holds a value (is not zero):

If oIE Is Nothing Then _
  Debug.Print "No Object assigned"

To view the contents of the integer oIE we first needs its address. In GB32 you can obtain an address of a variable in several ways. You may use VarPtr(oIE), or V:oIE, or *oIE. After obtaining the variable address it must be read, or peeked, to get the contents. Reading a Long or Int32 from some address is done using Long{addr}. The Trace statement uses the Hex function to convert the value to a hexadecimal format, the usual format for a memory address.

From the previous blog post Using OLEVIEW we learned how to process the calling of a property or method through late binding. To summarize, to execute a method or a property of the object an automation client can:

  1. Call GetIDsOfNames to "look up" the DispID for the method or property.
  2. Call Invoke to execute the method or property by using the DispID to index the array of function pointers.

All BASIC languages support this behavior behind the curtains. They provide the object dot-operator to call properties and methods through late binding. For instance, when you want to check to see if Internet Explorer is visible you may call the Visible property:

If oIE.Visible == True Then _
  Debug.Print "Is visible indeed"

After compiling this code the program will execute oIE’s interface-function GetIDsOfNames to "look up" the DispID for the property. It will then generate code to call Invoke to execute the method or property by using the DispID to index the array of function pointers (vtable). Calling Invoke is a bit of a hassle and is best left to the compiler.

Now what when the server gets new functions and new names. Unfortunately, you would need to recompile and redistribute the client application before it would be able to use the new properties and methods. In order to avoid this, you could use a ‘CallByName’ function to pass the new property and method names as strings, without changing the application.

In contrast with other programming languages GFA-BASIC features a function called _DispID(). This function allows you to call the objects GetIDsOfNames function to "look up" the DispID for the method or property. When you remember the blog post on Using OLEVIEW you might have noticed that every property and method is assigned a unique ID (integer value). Using _DispId(0bject,Name$) we can obtain exactly that unique value. For instance, this will display the ID value 402 in the Debug output window.

Trace _DispID(oIE, "Visible")

Obtaining the dispId of a method or property is only useful when you can use the integer value to call the IDispatch function Invoke(). Specifically for this purpose GFA-BASIC 32 provides us with a might piece of equipment; the dot-curly operator. To call Invoke using the dispId you can simply replace the name of the property or method with ‘{dispId}’.

Global Long dispIdVisible
dispIdVisible =  _DispID(oIE, "Visible")
Trace oIE.{dispIdVisible}
Trace oIE.{402}

How does VB6 do it?
If you’re interested, you should compare this elegance to the VB6 function CallByName. This function allows you to use a string to specify a property or method at run time. The signature for the CallByName function looks like this:

Result = CallByName(Object, ProcedureName, CallType, Arguments())

The first argument to CallByName takes the name of the object that you want to act upon. The second argument, ProcedureName, takes a string containing the name of the method or property procedure to be invoked. The CallType argument takes a constant representing the type of procedure to invoke: a method (vbMethod), a property let (vbLet), a property get (vbGet), or a property set (vbSet). The final argument is optional, it takes a variant array containing any arguments to the procedure.

Due to the elegant syntax, GB detects how to invoke the method or property. The parameters of a property or method don’t go in a Variant array. Due to the dot-curly syntax the parameters are specified as any other property or method call. The only thing you need to do yourself is retrieving the dispID, but this is of great advantage since now you are able to store the ID to use it over and over. The CallByName() function each time has to obtain dispID for the name passed.

Dlg 3D On is for Dialogs only

GFA-BASIC 16 (for Windows 3.1) offered the command Dlg 3D On. to get more appealing 3D effects for dialog boxes and controls. This command was invoked before a dialog box was defined and/or created, which was the same thing in GB16. Usually the command Dlg 3D On was placed at the start of the program so that all dialogs would benefit from the 3D effect. In the background the 16-bit system CTL3D.DLL was loaded, was responsible for the painting.

What is CTL3D?
The 16-bit CTL3D.DLL hooks into dialog creation and control creation and "subclasses" the standard windows controls to give them a more appealing 3D effect. To draw 3D effects the background of the dialog boxes was painted gray, or more precisely, painted using the COLOR_BTNFACE color. That made the 3D effects possible in the first place.
This technique was first used by Microsoft Excel version 4.0. The Excel team shared the technology with the rest of the industry. Since then, the use of CTL3D has become a de facto standard and is commonly used by professional Windows applications. GFA-BASIC 16 supported the use of this DLL directly using Dlg 3D On/Off.

Still present in GB32
Starting with Windows 95 a much more pleasing 3D look is provided by default. This made CTL3D unnecessary. Despite its absence in Windows 32-bits GFA-BASIC 32 still supports the the Dlg 3D command, for backwards compatibility. However, its implementation is quite different now. The 3D effect is not accomplished through a system DLL, but by setting the default background color of the dialog box to COLOR_BTNFACE.

Dlg 3D On only works for Dlg form Ocx objects, these are the forms created using the Dialog # / End Dialog commands and accessed with the object variable name Dlg_n, where n is an ordinal value between 0 and 31.

Starting with GB32 most attributes of windows and controls are managed through OCX properties and methods. Internally, all window management is routed through the COM wrappers of the system OCX controls. This is also true for the creation of Dialog # forms. The runtime runs exactly the same code as when you create an Ocx Form. Other (16-bits compatible) window commands like OpenW, ChildW, and ParentW are created by this code as well. However when a Form is created using the Dialog command, the runtime code converts the Dlg 3D and  DlgBase Xxx commands to the appropriate Form-Properties.

Dialog # id, x, y, w, h, tit$ [,flag [,height,font$] ]

The attributes of a dialog form may be set beforehand using the following commands: 

Command Meaning
Dlg 3D On Fills and sets background with COLOR_BTNFACE
Dlg 3D Off Use default Form background-color (default)
DlgBase Pixel Use x, y, w, h as pixels (default)
DlgBase Unit Use x, y, w, h as dialog base units
DlgBase InSide Use x, y, w, h as client size
DlgBase OutSide Use x, y, w, h as window outside (default)
DlgBase Font font$ Use font$ for all controls
DlgBase Bold Use a Bold version of font$
DlgBase Bold Off Use a Normal version of font$
Dlg Fill Fills and sets new background color

The font$ parameter overrules the DlgBase Font setting.
Afterwards the background color can be changed by using properties or by using the Dlg Fill command.

These Dlg commands are used in conjunction with Dialogs only.

30 November 2013

Using OLE/COM Object Viewer

Ever wondered how to get information about all properties and methods of the GFA-BASIC 32 OCX COM-objects?

To view GFA-BASIC OCX type library information, you can use the Microsoft OLE/COM Object Viewer utility that is included with the Microsoft Windows SDK kits.


The figure displays information from the GfaWin23.Ocx type library, a resource found in this DLL. More specifically, it shows the details for the Form Ocx and the CurrentX Get Property. You use the OLE-COM Object Viewer to view compiled type library information. The object viewer presents the COM classes in C/C++ syntax.

To view a type library with the OLE/COM Object Viewer:

  1. Find the OLE/COM Object Viewer application in the bin directory of the installation path.
  2. On the File menu, click View TypeLib, and browse to locate the type library you want to view (GfaWin23.Ocx)

Like the Object Browser that VB and Microsoft VBA use, the OLE/COM Object Viewer lists all the classes exposed in a type library, along with the methods and properties those classes support. For the programmer, the OLE/COM Object Viewer provides important information, such as function return types, argument types, and DISPIDs (which will be discussed shortly). You can use the information that the viewer provides in conjunction with the GB32 object model documentation.


Download SDK
The latest Windows Software Development Kit for Windows 8 (Windows SDK) contains headers, libraries, and a selection of tools that you can use when you create apps that run on Windows operating systems.
The Windows Development Kit (SDK)

I also advise to read Automating Microsoft Office 97 and Microsoft Office 2000 to refresh your memory on the binary layout of COM objects. You may take a look at the section “How an object can exposes its methods and properties”. It does so in two ways: by means of a dispatch interface and in its vtable. Also take a look at my blogs Build a COM object in GB32 (1) and    CreateObject.

A COM object exposing its functions through a vtable only, provide clients with early binding only. The compiler binds methods and property invocations to the vtable-function-pointers directly for more direct access and faster execution. An object that exposes its methods through both a dispinterface and its vtable supports a dual interface.

The DispID
You can examine type libraries in the OLE/COM Object Viewer to determine if an object provides a dual interface. An object that provides a dual interface specifies the dual attribute in its interface declaration. All GB32 OCX objects implement the IDispatch interface. It is this IDispatch interface that provides Automation clients with access to an object's content and functionality. An object's methods and properties collectively make up its dispatch interface (or dispinterface). Within the dispinterface, each method and property is identified by a unique member. This member is the function's dispatch identifier (or DispID).

A COM object can provide clients access to its functions using a dispinterface, an array of function names, and an array of function pointers that are indexed by DispIDs. In GB32 the execution of methods and properties through the dispatch interface is hidden behind the COM dot-operator on an Object data type. First see how GB32 executes properties and methods through early binding.

' Create new instance of the ImageList OCX.
' The Iml variable is of COM type (I)ImageList.
Dim Iml As New ImageList
' Access through early bindings; call the
' ImageHeight and ImageWidth directly through
' a function pointer.
Iml.ImageHeight = 16
Iml.ImageWidth = 16
Iml.Add  , "comp", LoadPicture(":MyComp")

See also: Dim As New

As you can see from OLE-VIEW, the IImageList interface is declared dual. So, the properties and methods are available at runtime as well (late binding). The GB32 compiler doesn’t put a reference to a function address, but stores the name of the method or property and the values of the parameters that must be passed. The compiler than inserts a call to Invoke() to have the program call the method or property at runtime by looking up the name of the function through GetIDsOfNames(). You may want to read the section on Binding in the same article Automating Microsoft Office 97 and Microsoft Office 2000

Note It is a VB/VBA convention to use the name of an interface a a new user-defined type and than skip the capital I from an interface name. So, IImageList in OLEVIEW becomes ImageList type in BASIC.

Now let us see how the method and properties of the ImageList type can be executed at runtime through late binding. The general BASIC Object data-type is an object consisting only of the IDispatch functions. The Object variable oIml doesn’t know about other interface functions ImageList supports. The compiler inserts code to execute the function .Count at runtime through the IImageList functions GetIDsOfNames and Invoke.

Dim oIml As Object      // An IDispatch object
Set oIml = Iml          // Assign to Object
Print oIml.Count        // late binding

To execute the Count property of the oIml object must call GetIDsOfNames to "look up" the DispID for the property. Subsequently, oIml calls Invoke to execute the property by using the DispID to locate the Count function address in the IImageList’s array of function pointers.

Next blog: GFA-BASIC 32 supports syntax and functions to look up the DispID and use Invoke.

06 October 2013

Debug is a runtime object

Closer examination of the Debug object reveals some interesting facts. Although the GFA-BASIC IDE offers some alternative actions to open the debug window, it is not an object owned by the IDE.

The Debug object is completely embedded (data and methods) in the GfaWin.Ocx, which is GFA-BASIC’s runtime. The Debug object is not dynamically created like other COM objects. You don’t use the Ocx command or a New clause in a Dim statement. The Debug object is a global (static) object located in the data section of the DLL. Other examples of static runtime objects are App, Screen, Printer, Forms, and Err.

Note – Most COM objects are – by nature – dynamically created at runtime. In GFA-BASIC they are either allocated using the Ocx (or OcxOcx) command, or with the New clause in a Dim statement. These commands create and allocate memory on runtime. Like the String datatype, a COM object is always stored and accessed by a pointer. A COM object variable occupies only 32 bits and points to a block of memory allocated from the free store. When the variable contains the value 0 (not pointing to a memory address) the object is said to be Nothing. There are some more functions that implicitly create dynamic COM objects, like LoadForm and LoadPicture. Each COM object created by a GFA-BASIC command is destroyed by GFA-BASIC, whether it is a static object or dynamic object.

The Debug object manages the window
Thee Debug object isn’t allocated at runtime, it is available all times. You can immediately start invoking properties and methods on the Debug object. Although the purpose of the debug output window is to display state information at runtime, the Debug object is mainly used to control or manage the debug output window. The debug output window is a modeless, top level, non-owned window with one child control; a standard EDIT control. Many properties and methods control the appearance and behavior of the debug output window and/or its edit control. For more information of the properties and methods look at the descriptions in the help-file or press a dot after the Debug keyword in the editor. Most of them speak for them selves.

Like your application can use the Debug object, the IDE can use the output window as well. The IDE uses the same static Debug object as your application. Any changes the IDE makes are reflected in your application, and vice versa. For instance, when the IDE hides the debug output window, your application must re-show it explicitly.
The IDE offers you two alternatives to show the output window.

  1. By selecting the IDE menu bar View | Toggle Output Window [Alt+3] at design time.
  2. By selecting the tray icon popup menu item at run-time.

Your application can provide its own means of operation to open the debug output window. The debug window could be used for logging, without actually showing the window.

So, whether your application or the IDE controls the debug output window, they both use the same static Debug object in the runtime. Therefor it is important to know what happens in the background.

The Debug thread
First of all, at the first opportunity – when one of the Debug object’s properties or methods is invoked – a new thread is created. As with all good threads it is not destroyed before the application ends; that is when the DLL runtime unloads from memory. When the GFA-BASIC IDE starts executing the thread isn’t started immediately. Only when your GFA-BASIC application, a GLL editor extension, or one of the IDE commands to show the debug window, are applied the thread is actually started.

The debug thread registers the DebugClass window class and creates an instance of the window class (top-level). Note that the window is displayed in the taskbar. Once the window is created the thread enters an infinite message retrieval loop (inside the thread) and handles the dispatching of messages to the DebugClass window procedure, located in the runtime. The window procedure itself is responsible for responding to the messages of the debug output window. One of the messages the window procedure must handle is the WM_SYSCOMMAND, because the debug window thread adds a system menu item to the window (Always on Top). The window procedure either responds by setting the top-level window to the top of the top-level-windows Z-order (HWND_TOPMOST), or by setting it to the bottom of the Z-order (HWND_BOTTOM), which by the way doesn’t mean that it will disappear immediately.

The position is saved automatically
Another message the thread’s window procedure handles is WM_EXITSIZEMOVE. This saves the (new) position of the ‘DebugClass’ window in the registry. It saves the position as a binary value from a RECT structure. It is saved under the a sub key name of ‘DebPos’ in ‘HKEY_CURRENT_USER/Software/GFA/Basic’. When this key doesn’t exist, it is created. When your customers application uses the debug window, the position will be saved in this registry key of your customers PC. Also note that your customer has the ‘Always on Top’ option available. This setting isn’t stored in the registry. (BTW the window position isn’t saved when the output window is in a minimized or maximized state.)

Give it an owner
I find the debug window - unowned toplevel - completely living on its own quite annoying. I think it should be owned by the main window (and thread) of the application that is using it. In case of GFABASIC this should be the Gfa_hWnd window, in case of a customer application, your main windows handle.

~SetWindowLong(Debug.hWnd, GWL_HWNDPARENT, Gfa_hWnd)
Assert GetWindow(Debug.hWnd, GW_OWNER) == Gfa_hWnd

As an example I added the Assert line. I was a little unsure what exactly setting GWL_HWNDPARENT would do and tested the result for what I expected it to do. Anyway, giving it an owner removes the Debug window from the taskbar and makes it behave like its owner. When the owner (Gfa_hWnd) is minimized, the debug output window is minimized. When the owner is (de-)activated the output window is de-activated.

Give it a different font
The edit control is the one and only child window of the debug output window. It has ID number 1 and its window handle is obtained using:

hEditCtrl = DlgItem(Debug.hWnd, 1)

Since it uses a non mono space font you might want to create your own font using API functions and then assign it to the edit control.

SendMessage hEditCtrl, WM_SETFONT, hFont, MakeWParam(1,0)


20 July 2013

What’s that Google+ Button Besides the Articles?

If you’ve been reading GFA-BASIC 32 articles for any length of time, you might have seen the “Recommend this on Google” button… I’m not a fan of plugging in every different crazy social network and putting widgets and buttons all over the blog.

So why do the Google+ button? Because Google uses these scores when they do their search rankings, and GFA-BASIC can use all the help it can get to keep these articles ranking well in Google.

So the next time you click that button, know that the community is thankful for your help!

25 June 2013

What to do with an OLE_COLOR?

An OCX/ActiveX control color property can be assigned any valid Win32 color reference. However, the OCX/COM libraries provide a special data type for color properties, the OLE_COLOR data type. This new type was invented to give VB-like programs an opportunity to differentiate between a normal Win32 color reference and system colors. These programs could then present a special color-selection dialog box that allowed the selection of system colors. The snapshot of the GB32 Ole-color selection is shown below.


RGB colors are of type COLORREF
Like an RGB-color value, an OLE_COLOR data type is internally represented as a 32-bit long integer. An RGB-color is referred to as a COLORREF value and is used with GDI device context functions. A COLORREF is simply defined as a 32-bit value used to specify an red, green, and blue components of a color requiring only 3 bytes. When specifying an explicit RGB color, the COLORREF value has the following hexadecimal form.


The low-order byte contains a value for the relative intensity of red, the second byte contains a value for green, and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF.
To create a COLORREF color value, you can use the GB32 RGB() function. To extract the individual values for the red, green, and blue components of a color value, use the GetRValue, GetGValue, and GetBValue functions, respectively. For performance reasons these GFA-BASIC 32 functions are directly translated to assembly code; they are not implemented as function calls.

The OLE_COLOR type
When a COM object property (most often .ForeColor and .BackColor only) requires an OLE_COLOR color, you can either pass an RGB  value (COLORREF) or a COM specific formatted system color index value. A COM specific format has it’s high-byte set 0x80. An OLE_COLOR can have two formats only:

  • 0x00bbggrr (COLORREF value)
  • 0x800000xx, where xx is the index used by GetSysColor().

The object doesn’t do much with the OLE_COLOR value, it is more a kind of a storage type. For instance, you cannot pass an OLE_COLOR to a GDI device context handle. GDI doesn’t know what to do with a COM formatted system index color (0x800000xx). The OLE_COLOR value is simply saved in the private data of the COM object and remains unchanged until the application explicitly changes the value again. This way, the Get-color-property variant of the Put-color-property will return exactly the same value as was first put in.

How the OLE_COLOR is used
Since the format of the OLE_COLOR data type isn’t known to Win32 drawing functions, they must be converted to RGB colors first. Usually, the OLE_COLOR is converted on a just-in-time basis. Just before a painting operation is performed the OLE_COLOR (32-bit long integer) is tested for a high-byte value of 0x80. When the high-byte is indeed 0x80, the low-byte value is used as a parameter to the GetSysColor() API function, which in turn returns the RGB color value of the specified display element. See the code below.

Aside: Identifying display elements
Display elements are the parts of a window and the display that appear on the system display screen. These elements are identified using the API COLOR_* constants, like COLOR_BTNFACE, COLOR_WINDOW, etc. These API constants may also be used in the GFA-BASIC 32 function SysCol(idx), which is slightly easier to use and a bit faster due to caching.

Dim rgb% = SysCol(COLOR_WINDOW)

GFA-BASIC 32 also defines a set of OLE_COLOR constants to identify the system display elements. These constants are very much like the Windows API COLOR_* constants. However, instead starting their names with ‘COLOR_’ they start with ‘col’, like colBtnFace and colWindow. These GB32 OLE_COLOR constants have the format of 0x800000xx, where xx is the index for the display element. See the code below.

Convert an OLE_COLOR
When you want to use an OLE_COLOR value, make sure to convert the OLE_COLOR to a COLORREF (RGB) value first. This is the only color format Win32 understands. In GB32 you get hold of an OLE_COLOR when you use one the col* constants or retrieve a color from one of the Ocx-color properties. For instance, when you want to use the same color as the form’s background, you might very well end up with an OLE_COLOR with the high-byte set to 0x80.

Now, there are two possible ways to convert an OLE_COLOR to a COLORREF value.

1. Manually, in your code. For example this converts to an RGB-value:

Trace Hex(SysCol(colBtnFace))   ' =0 (SysCol: what is a colBtnFace?)
Trace Hex(colBtnFace)           ' =8000000F (an OLE_COLOR)
Trace Hex(OleToRGB(colBtnFace)) ' =F0F0F0 (the RGB value)
Trace Hex(OleToRGB(0x667788))   ' =667788 (no conversion)

Function OleToRGB(olecolor As Long) As Long Naked
  If (olecolor And 0xFF000000) == 0x80000000
    Return SysCol(olecolor And 0xFF)  ' LoByte
    Return olecolor                   ' RGB!

2. Use the system OLE function OleTranslateColor()

Declare Function OleTranslateColor Lib "oleaut32.dll" ( _
  ByVal OleColor As Long, _
  ByVal hPal As Handle, _
  ByRef ColorRef As Long) As Long

Dim rgb As Long Long

If OleTranslateColor(colBtnFace, Null, rgb) == S_OK Then _ Trace Hex(rgb)

The second option using OleTranlateColor() might be preferable because it can also return other GDI color formats, like a palette-index value. In addition in case of an error, it let you investigate the type of the error. See the SDK for more info.

More flexibility
You can use OLE_COLOR types with the GB32 graphic commands, though. All drawing statements, font statements, and color statements accept an OLE_COLOR type. GB32 converts the OLE_COLOR to a COLORREF before it invokes the corresponding GDI function.

Another nice page on GB32

Sometimes I scan the internet for GFA-BASIC 32 references. Recently I stumbled upon this site http://basic.mindteq.com/index.php?i=81 with a comment from Bruce Bell. He wrote a very nice summary of the GFA-BASIC 32 essentials. Chapeau!

23 June 2013

The Align Property of Command, Checkbox, and Option

The Align property of the Ocx controls Command, Checkbox and Option differ from other Ocx controls. The documentation for Align says that it indicates how an Ocx control is placed inside its parent or owner Ocx control, also called docking. Several predefined constants (basNoAlign (0), basTop (1), basBottom (2), basLeft (3), and basRight (4))  are provided to help using the correct docking value with Align.

The buttons are different
In GFA-BASIC32 the Windows BUTTON class controls (push)button, checkbox, and radio-button are implemented as Ocx Command, Ocx Checkbox, and Ocx Option, respectively. The position of the contents of the BUTTON control can be changed by applying a predefined BUTTON-style alignment value. These are defined in the winuser.h SDK include file:

#define BS_LEFT             0x00000100
#define BS_RIGHT            0x00000200
#define BS_CENTER           0x00000300
#define BS_TOP              0x00000400
#define BS_BOTTOM           0x00000800
#define BS_VCENTER          0x00000C00

These values can be applied using API functions or using the WinStyle property of the Ocx controls. In addition, these style bits can be set using the Align property of the BUTTON class Ocx controls (Command, Checkbox, and Option). However, the values that you can assign to Align are different than the values used with the docking purpose of Align. The documentation lacks proper explanation of using the Align property with buttons. (At least in the English help file.)So let me fill the gap.
The position of the contents of the BUTTON controls can be set using a value between 0 and 10, but not 3 and 7. There meaning - as described by the official GB32 documentation -and the corresponding button styles are listed below.

Value Position BUTTON Style Value
0 Center Normal H/V centered 0x00000000
1 Left BS_LEFT (vertical centered) 0x00000100
2 Right BS_RIGHT (vertical centered) 0x00000200
3 no meaning* BS_CENTER 0x00000300
4 Top BS_TOP 0x00000400
5 TopLeft BS_TOP | BS_LEFT 0x00000400 | 0x00000100
6 TopRight BS_TOP | BS_RIGHT 0x00000400 | 0x00000200
7 no meaning* BS_TOP | BS_CENTER 0x00000400 | 0x00000300
8 Bottom BS_BOTTOM 0x00000800
9 BottomLeft BS_BOTTOM | BS_LEFT 0x00000800 | 0x00000100
10 BottomRight BS_BOTTOM | BS_RIGHT 0x00000800 | 0x00000200

When one of the position values from the first column is passed to the Align property the value is shifted left 8 bits and then sent to the BUTTON control using

SendMessage(ocx.hWnd, BM_SETSTYLE, position, 1)
* The no meaning values 3 and 7 can be used in code, not in the Form Editor. When used in code, the internal GB32 function that implements Align will accept any value between 0 and 15! It simply shifts the value 8 bits left and sends it to the BUTTON control.

So, the value of the Align property is used to position the contents of a BUTTON control Ocx. The value is converted to a BS_* constant value as defined in the SDK and passed to the BUTTON control. In this particular case the Align property has a different meaning. Perhaps, it should be named ‘Alignment’ as with the Label Ocx controls.

19 May 2013

Mailinglist Is Back!

From Juergen, the man who provides the GFA-BASIC mailing list on his private server for the past 10-15(?) years:

Hi folks, my domain @liebenstein.de was for a time not available, because the domain was put mistakenly on a black list and out of name server listings. With that also the mailing list didn't work of course. Please excuse this, the list is now
available again.

Thanks, Juergen!

30 April 2013

GFABASIC Mailing-list gone?

Many of us now receive this notification since the 4th of April.

This page can't be displayed
  • Make sure the web address http://gfa-basic.liebenstein.de is correct.
  • Look for the page with your search engine.
  • Refresh the page in a few minutes.

The moderator Juergen, cannot be reached by his GB mailing list's e-mail address. Either he doesn't know the list in reachable or he unplugged it.
Questions can be send to this blog's e-mail address or at my personal address. I will make them public and when the mailing list remains off line I will start my own list.

07 April 2013

Favorite: On GoSub/GoTo/Call

One of my favorite programming constructs in GFA-BASIC is, and always has always been, the On value GoXxx statements. Although, I must admit, there was a time I doubt the usefulness and legality of this command, because C/C++ doesn’t offer such a branch instruction. At those times I was under the impression that it was a typical BASIC overkill command. However, it is definitely not, on the contrary! These statements let GFA-BASIC produce optimized branching code through the use of jump tables. C/C++ compilers can do this only when their ‘optimize to fast code’ - switch is set. Since C/C++ doesn’t support jump tables as a language construct, these compilers crunch together a switch/case block and try to turn it in a jump table just like GFA-BASIC does by default. These are the statements that produce highly optimized branching code without setting a compiler option.

On n GoSub label1, label2, …
On n GoTo label1, label2, …
On n Call Proc1, Proc2, …

My most favorite version is On GoSub. This allows for executing local subroutines labeled by a Label: and ended with a Return statement. This version is not compatible to C/C++, these compilers produce code compatible to GFA-BASIC’s On GoTo.

Not in an Editor Extension
As I mostly program editor extensions, I was surprised to got in problems with these branch statements. GFA-BASIC, like Visual C++, creates a jump table at the end of a function/procedure. However GFA-BASIC hard-wires the address of the jump table, with the presumption that the code starts at $400000 (hInstance). With dynamically loaded GLLs, that place was reserved for the IDE executable image (that is where the code is loaded). When the GLL reaches the execution of the On GoSub code it reads the execution address of the labels from the IDE’s code text section. To the GLL this code contains rubbish. When the GLL is loaded not all the addresses in the GLL code aren’t updated correctly.

As my goal is to create code as efficient as possible, I am a bit disappointed and maybe I will try to fix the GLL-loader.

07 February 2013

SetFont 0 or Null?

In 2002 Peter Harder wrote:  "SetFont 0" oder "SetFont ungueltiges_handle%" sorgen im Gegensatz zu GFA16 bei GB32 für einen Programmabbruch. Tückisch vor allem  dann, wenn dieses Problem beim Umschreiben eines GFA16-Programms ' erst beim Kunden auffällt; ein Hinweis in der Onlinehilfe auf  diesen Unterschied fehlt.

What is this about SetFont?
In previous versions of GB the statement SetFont 0  was often used to select a default stock object font in the current active device context. Peter’s remark suggests that this functionality is missing from GFA-BASIC 32. However, it isn’t actually missing, but the data type of the argument is a Variant, rather then an integer. The 0 value is automatically converted to a Numeric Variant (data subtype = basInt) with value 0. This means: 0 is a valid numeric value and is handled as if the font-handle with value 0 is passed to SetFont.

It throws an error
The SetFont library routine checks for a numeric value in the Variant and uses that value to select a stock object. However, the valid value 0 references the WHITE_BRUSH stock object and not a font. SetFont stops and throws an error. ( The error “Illegal Function call”, which, of course, should have been “Invalid Parameter”.)

Use Null instead
To have SetFont select a stock object, to be precise, the DEFAULT_GUI_FONT, the Variant argument of SetFont must be set to the VT_NULL variant subtype. This is done by using the Null constant.

SetFont Null

The Null keyword is used with a Variant to indicate that it intentionally contains no valid data.

But what if you have a variable that is holding a font handle? Well, in case the font handle is 0, you would want to pass a VT_NULL variant subtype, so you must convert it to Null. You could use the explicit Null constant as above, but you can also use an undocumented function Null(value), which is replaced by a simple Null.

Global font%
If font%==
SetFont Null(font%

19 January 2013

Runtime Update 1181

The update Build 1180 from last week caused some problems due to a new bug that manifested itself as a result of the fixes. The problem was the Form Close method. It invoked a function that was called again when the window was actually destroyed. At that point the contents of the variables were undefined and the Close method halted with an Access Violation error.

Download: GFAWin23.Ocx Runtime

14 January 2013

Using Fonts the old-way

The old-style font commands from GFA-BASIC for Windows 16 can still be used in GB32. However before using them you should be aware of an essential difference between GB32 and GB16. Beside this you should also know what the consequences are when applying the GB16 font commands.

The GB LOGFONT structure
In GB16 the font commands applies to one, and only one, internally maintained, global LOGFONT structure (user defined type). In GB32 there are multiple LOGFONT structures and none of them is a global variable. The LOGFONT structure is now part of a Form object and the font commands now work on the LOGFONT of the current active Form (Me)

The LOGFONT type is defined in wingdi.inc.g32 located in the Include directory of your GB32 installation.

' Logical Font (wingdi.h)
Global Const LF_FACESIZE = 32
Global Const LF_FULLFACESIZE = 64

  lfHeight As Long
  lfWidth As Long
  lfEscapement As Long
  lfOrientation As Long
  lfWeight As Long
  lfItalic As Byte
  lfUnderline As Byte
  lfStrikeOut As Byte
  lfCharSet As Byte
  lfOutPrecision As Byte
  lfClipPrecision As Byte
  lfQuality As Byte
  lfPitchAndFamily As Byte
  lfFaceName(LF_FACESIZE) As Byte
End Type

Regardless of the GB version, the members of the current LOGFONT variable are set and read using the same set of commands. In GB16 they are applied to the one global variable, but in GB32 they still set and read the LOGFONT members from the current active Form (Me).

GB-Command Description
FONT member value sets a value to a member
RFONT member variable reads a member value into a variable
variable$ = _Font$ copies all logfont-members into a string
_Font$ = variable$ sets all logfont-members from a string
Dlg Font sets all logfont members from a users font selection
Font To hfnt Creates a logical font from logfont
FreeFont hfnt Deletes a logical font
GetFont hfnt Obtains loglont values from a logical font
SetFont hfnt Selects the logical font into the window's DC

After filling the LOGFONT members (using Font name, _Font$, or Dlg Font) the Font To hfnt invokes the GDI function CreateFontIndirect() which returns a Windows handle to the font created. This functions allocates memory whose memory handle is returned in the hfnt variable (32-bits). This font memory must be released by the application explicitly using FreeFont hfnt.
The GDI fontmapper creates the font that best matches the values in the LOGFONT structure. However, they might be different from what was requested. To obtain the attributes of the GDI created font, the application would use GetFont hfnt. This reloads the LOGFONT values from the actual font handle.

What about SetFont?
In GB32 this commands invokes a series of complex procedures. In GB16 it was as simple as selecting the logical GDI font handle into the current device context. In addition, in GB16 the current device context could be manipulated using SetDC, which is obsolete in the 32-bits version. Of course, eventually, GB32 will select a font handle into a device context like in GB16, but GB32 goes the COM way. As such the GB command SetFont hfnt creates a hidden Font object and performs a Set Me.Font = hiddenFont (from hfnt).

Finally, any font the application created the old way using Font To must(!) be released explicitly when it is no longer in use. Meaning after that some other font has been set. (Either using SetFont or using the Form's property Font.)

13 January 2013

Removal of update Build 1180

Today, 13 January 2013, I temporarly have removed Ocx1180. The runtime OCX Build1180 (from 06-01-2013) because of reported runtime errors. This Build should have fixed memory leaks with Form.Picture and Image.Picture.

Hopefully, the update can be restored soon.

11 January 2013

Use the Explorer Preview Pane

This time I want to share a tip with you. I'm a big fan of the Explorer Preview Pane a facility that can show the contents if files next to the files in a separate pane. It allows and helps me to quickly scan C/C++ (header) files, readme-text files, and other plain text files. Most often it helps to scan through MSWord en PDF files as well. I use it for GFA-BASIC 32 files as well.
Preview GFA-BASIC 32 files
GB32 files are plain text files as well. So it would only be logical (as Spock would say) to view them in the preview pane as well. It is not only logical but possible as well. You can assign the '.g32' extension to the default Text Viewer of Windows Explorer by using a registry hack. However, this is not only cumbersome, but a bit complex as well see http://blogs.msdn.com/b/toub/archive/2006/12/14/preview-handler-association-editor.aspx. In the article Stephen Taub, author of the program, describes the Preview Handler Association Editor tool.
This utility helps in assigning all registered file-extensions to a preview handler. Note that since Windows Vista the GFA-BASIC 32 file extension .g32 can only registered when GB32 is started in Administrator Mode. Then go to Properties and click the button to register the g32 and lg32 file extensions.
Changing the font
To change the standard font of the preview pane isn't difficult, because the pane always uses the current Notepad font. By changing the default font of Notepad you change the font of preview pane when using the Windows TXT Previewer.
Procedure: Launch Notepad and select Format/Font... from the menu bar. Change the font and close Notepad. Now text files should be rendered in the font you just selected.

07 January 2013

Download Update Ocx Build 1180

The memory leak bugs described in Memory Leak with Form.Picture Object en Memory leak with Image Ocx are fixed in the latest runtime version. The update of the file GfaWin23.Ocx has build number 1180. It can be download from the download page.

Go To Download Page

Note Do not forget to replace all occurrences of this file. Often it is placed in a program's directory or in a Windows system directory!

04 January 2013

Memory Leak on Image Ocx

At the end of 2012 Peter Heinzig posted a sample showing GFA-BASIC 32 memory leaks with the Form and Image Ocx. In Memory leak with Form.Picture I focused on the Form object and a remedy against the memory leak. In the meantime I investigated the Image Ocx and can confirm a memory leak when the Ocx control is destroyed. Just like the Form Object the Image Ocx doesn't release it's Picture object. The remedy is actually the same. In the parent Form Ocx _Destroy sub event add a command to release the Picture property of the image control.

The solutions presented here are applicable on all versions of GFA-BASIC 32. However I hope to build an update of the runtime as soon as possible. I hope these are the only memory leaks, but it takes time to verify these are the only Picture objects that aren't released after a program has been closed.

31 December 2012

Printing a listing on another printer

If you are running a Windows Vista or Windows 7 operating system, then the procedure to select different printers has changed from earlier versions of Windows. Starting with Windows Vista the "Printer ..." button is missing from the common dialog Page Setup dialog box. This is a consequence of the newer Windows operating systems. Now if you want to change printers or print drivers, you must change the default printer from the “Devices and Printers” window

How does this affect printing from GFA-BASIC 32?
To print a listing you can select Print in the File submenu. Depending on the presence of a text-selection, Gfa_Print will either print the entire listing or the current selection only. The text is printed immediately, without an option to select a different printer or to cancel the print job.

Initially, when you haven't printed before, the listing is sent to the default printer using default settings. At very first time, on my default printer, this produces lines in a vey hard to read small font size printed in the upper left corner of the paper.
Now I'm aware of this behavior, I make sure to set the printer page options before I  start printing for the first time.
The printer settings are available in the Printer Tab in the GFA-BASIC 32 Properties dialog box. The top two buttons are used to customize GB32's printing options.

GB32 Properties Printer

Selecting the top button labeled 'Page Setup' will bring up the Page Setup common dialog box. The Page Setup dialog box allows the user to set the paper size, source, orientation, and margins for printing. Starting with Windows Vista the common dialog box that pops up in GFA-BASIC 32 looks like this. The margin settings are initialized to zero, so it is logical that the listing is printed in the top-left corner of the paper.

GB32 PageSetup

After changing the page settings and selecting OK, GFA-BASIC 32 updates the top button in the Printer Tab with the name of the Printer (here Lexmark).

  • Due to a bug in the GFA-BASICs English string data the button text isn't shown properly. Rather than providing the printer name it only shows the word 'Printer'. (The first image shows a fixed version of the IDE.)

Applying new settings
The Page Setup values aren't applied before selecting the OK button in the GFA-BASIC Properties dialog box. The same is true for values from the other tabs (Editor and Compiler). 
The printer settings are applied to some global application variables and stored in 4 registry values in 'HCKU\Software\GFA\Basic' register sub keys:

Printer String containing DEVNAMES values
PrinterDMF Data containing relevant DEVMODE values
PrinterFont Compressed LOGFONT structure
PrinterPage Margins, MarginMetrics, Options. Used to initialize the Properties Print Page

At the next start the GFA-BASIC IDE reads back the "PrinterPage" values from the registry and assigns them to the global Printer Page variables. These values are used to initialize the controls of the Printer Properties Page (hence the name PrinterPage).

The "Printer" and "PrinterDMF" registry values contain device specific information. When the actual process of printing is started these values are used to create a printer device context. In case the values are missing or corrupted GFA-BASIC will obtain a device context for the default printer and starts printing without any user intervention.

How changes affect GB32
If you paid attention, you will have noticed that GFA-BASIC 32 supports the logic for using different printer than the default printer, but lacks the possibility to select one. How come? Well in all their wisdom Microsoft decided to change the Page Setup common dialog box starting with Windows Vista. Previously, until Windows XP, the Page Setup common dialog box contained a third button labeled 'Printer ...". It was this button that allowed the user to select a different printer from the Page Setup dialog box.

Workaround? Hardly!
When GFA-BASIC 32 was released it could not be known that MS would remove the "Printer ..." button. GB32's printer selection logic was build entirely around this button in the Page Setup dialog. That was - and still is - the only way to select a different printer. The only remaining option is to set another printer as the default printer from the Control Panel, although that wouldn't suffice. You should also remove the registry settings "Printer" and "PrinterDMF".

By providing this background information I'm hoping for some input as of how to get an actually working hotfix.

29 December 2012

Memory Leak with Form.Picture Object

When you assign an image to the Picture property of a Form Ocx, and don't release the Picture explicitly, a memory leak occurs when the Form is destroyed.

An image can be assigned using the Form-Editor Properties window in the sidebar. For a Form object the Properties window shows a Picture property that can be assigned an image (bitmap, icon, cursor, GIF, JPEG, and metafiles) by double clicking in the value column. Behind the scenes the LoadForm command - that is used to load a Form created with the Form-Editor - will create a COM Picture object on behalf of the Form. The dynamically allocated Picture COM object is then assigned to the Form.Picture property. 
However, a program may also set a Picture object to the Form.Picture property explicitly in code.

The memory leak occurs when the Form is closed. In the process of destroying all resources the Picture object is simply forgotten. The memory for the image is never released and the reference count on the COM object never reaches zero. Not only the memory necessary to store the image, but the memory allocated for the COM object will remain occupied. The memory used to store a bitmap can be of a considerable size and after some time you may even run out of memory. This most likely will present itself after RUNning a program multiple times within the IDE.

The best place to set the Picture Object to Nothing is within the Form_Destroy() event sub. A program cannot release the object when the Form has gone (==Nothing).

The leaked memory can never be reclaimed, because after the Form is destroyed the pointer to the Picture's COM Object is zeroed out. Selecting 'Cleanup Resources' from the Project menu will not work.

16 November 2012

Windows 8: Download WinHlp32.exe

GFA-BASIC 32 for Windows works perfectly well under Windows 8 (Win32/COM). GB32 is the ultimate professional BASIC to write native Windows 32 desktop programs to be compatible with older OSes and the latest Windows OS Win 8.

However to be useful with Windows 8 you will need to display the older-formatted help file using WinHlp32.exe. This program is required to display 32-bit Help files that have the ".hlp" file name extension. To view .hlp files on Windows 8, you need to install this application.

Download it from Microsoft Download Center.

11 October 2012

An owned Form

Until of the older set of chm MSDN Library files (<= October 2001) were replaced by the newer MSHELP, the MSDN contained an article called "Win32 Window Hierarchy and Styles" by Kyle Marsh, September 29, 1993. This article explains how top-level windows (aka Forms) relate to each other.

Form is a top-level window
A Form window, whether is is created using OpenW, Dialog, or Form, is a top-level window by default. A top-level window is any window that is not a child window. Top-level windows do not have the WS_CHILD style. All top-level windows are also connected to the desktop window through the parent window handle, GetParent(). Top-level windows are connected to the desktop window as if they were child windows of the desktop, and can be considered children of the desktop in that parent/child navigation techniques can be used to move between a top-level window and the desktop window. All top-level windows are displayed in the client area of the desktop window and thus behave as if they were children of the desktop for display purposes.

The parent window
Each window, being a top-level or a child window, has a parent window. The desktop window occupies the first level of the windows hierarchy and top-level windows occupy the second level. Child windows, which are windows created with the WS_CHILD style, occupy all other levels. Child windows connect to their parent window in the same way top-level windows connect to the desktop window.

The owned window
Top-level windows can own or be owned by other top-level windows. One Form can own another Form. An owned window is always displayed above its owner in the Z order and is hidden when its owner is minimized. Try this and see what happens, you cannot display Form Win_1 on top of Form Win_2:

OpenW 1
Me.Caption = Me.Name
OpenW Owner Win_1 , 2
Me.Caption = Me.Name
Until Me Is Nothing

Win_2 is owned by Win_1. Owned windows are not hidden when their owner is hidden. Thus, if window #1 is minimized, window #2 is hidden as well.
BTW you can set the owner using the designer in the Properties window. A Form has a an Owned property that can be set to True. After loading the Form using LoadForm the current active Form as referenced by Me will be set as the owner.

On the API level an owned window relationship is created by passing the window handle to the owner window in the hwndParent parameter of the CreateWindow() function. GB32 passes the window handle of the Form object specified in the Owner clause in the OpenW statement. To top-level window #2, window #1 is the owner, but not its parent window. The parent window for both Forms is the desktop window.
The GetParent() API function is not used to obtain the owner of a top-level window, that would return the desktop window handle. Insert the following lines before the start of the message loop. Both will return Null (0).

Print GetParent(Win_1.hWnd)
Print GetParent(Win_2.hWnd)

To obtain the owner GetWindow(hWnd, GW_OWNER) API function should be used. Insert these lines as well, and see how their results differ.

Print GetWindow(Win_1.hWnd, GW_OWNER)
Print GetWindow(Win_2.hWnd, GW_OWNER)

Finally, closing the owned top-level Win_2 won't automatically close Win_1. After Win_2 has been destroyed the current Form Me is set to Win_1. The global message loop will not end until Me == Nothing, which will not happen until Win_1 has been closed.

25 July 2012

Desktop Applications Again

PCWorld featured an article on changing habits of users of desktop, web, and smartphone software. Some quotes.

Cloud computing
"We had a thesis that people did not want to install software; that the cloud meant that people could use a browser to interact with software and would never have to install anything. We were completely wrong,” Jones says. “People love installing software"

The Web is out
No more Web-based applications: "But given what developers have discovered firsthand, we may see users clamor for native desktop apps, where they previously deemed Web apps to be sufficient."

Also read the blogs referenced in this article. GFA-BASIC 32 survived its time.

18 July 2012

How does GB32 define a word?

Did you ever realize how GB32 defines a word? Is it consistent across the different editor operations? Does a Ctrl-Left keyboard shortcut point to same word start as Ctrl-F? The Ctrl-F accelerator shows the Find Dialog Box where the Find What edit text control defaults to the current word. Is this the same word that is used in Ctrl-Left and Ctrl-Right actions? And what about the mouse double-click? What word does the editor use for the FindNextWord, to locate the next occurrence of that word? An example.

Global iVar1% = $4DC41C
Dim dd As Double = 2.45!

The next table shows the result of the 'current word' used to start the operation.

Word Ctrl Right Find Dlg Double Click
Global Global Global Global
iVar1% iVar1% iVar1 iVar1%
$4DC41C 4DC41C 4DC41C $4DC41C
2.45! 2.45! 2 2 or 45, depending on the position of the caret

Disturbing? At least confusing, because it isn't consistent. To me the whole module containing the editor's find and replace code seems a bit clumsy. (Maybe Frank Ostrowski was somewhat distracted during its development.) I can only guess what leaded to this inconsistency. The $AutoPostFix directive may have caused the decision to use the variable name without a postfix with the Find Dialog. Anyway, I don't like it. In my opinion all operations that determine a word should select the same word and the green marked words seem to be best candidate.

If there would be separate functions that return the current word, it would give me a starting point. Unfortunately, all operations mentioned above have their own getcurrentword algorithm. Another set back, by now I hoped to have had implemented the COM support I promised.

16 July 2012

Efficiently building a String

If you need to build a string by adding lots of pieces together, GFA-BASIC's string handling is relative slow because a new string is created in memory every time a new piece is added.

Often, alternatives are used like string builder functions. String builders allocate a string chunk and then uses memory copy methods to manipulate the data within the same string's memory. You'll find them in all frameworks and libraries of popular programming languages.

GB32 offers an efficient string builder as well, although it is bit hidden. The sprintf() function reserves a chunk of stack memory and uses memory copy functions to copy characters form the source string to a destination string. When it hits on a data placeholder in the source string it copies the data into destination string. Only when all characters and data are copied to destination buffer, the stack buffer in converted to a an actual String.

The difference between the two methods is illustrated below:

Dim sEdPos As String
' Assemble a caret position in a long
Dim EdPos As Long = MakeLong(12, 1)
' Put the string together
sEdPos = "Line: " + Dec(HiWord(EdPos)) + _
  " Column: " + Dec(LoWord(EdPos))
' Or use sprintf()
sEdPos = sprintf("Line: %d Column: %d", _
  HiWord(EdPos), LoWord(EdPos))

12 July 2012

(GB/VB)BASIC isn't dead

You are invited to visit "TIOBE Programming Community Index" at : http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html

See the trends in computer language. Right now plain C enjoys the first position, with Java and C++ slowly going down and Objective-C going up. (Visual) Basic remains steady at position 6. Don't confuse it with VB.NET, which is located at position 15. But VB.NET has an increasing audience also.

07 July 2012

Write # or Print #

Why does the GB32 Hash type use Write to save the data from a hash table (= dictionary)?

The correct answer is: In contrast with Print #, Write # uses a non-locale format. In Basic we often choose Print # over Write #, but both have their own goal. It has even been suggested that Write is a relic from prehistoric BASICs. However, this isn't true. To be able to correctly read data from a file into variables using Input #, use the Write # statement instead of the Print # statement to write the data to the files. Using Write # ensures each separate data field is properly delimited.

Both, the Print # and Write # commands, can be used to write data to a sequential text file, however the commands cause the information to be written to the text file differently.

The Write # statement is used to write raw data to the text file as comma- delimited and has the following syntax:

Write #filenumber[,outputlist]

All data written to the file using Print # is internationally aware; that is, the data is properly formatted/converted using the appropriate decimal separator. The syntax is similar, but the result quite different.

Print #filenumber[,outputlist]

Difference 1 – Quotation marks
The Write# command places quotation marks around all text values (strings), but not numeric data. The Date fields are surrounded with #s (pound signs). 
The Input# command is used to retrieve values from a text-only file created with the Write# statement (removes quotation marks from strings).

The Print# command does not enclose the data in quotation marks.

Difference 2 – Delimiter
The Write # command separates two or more values on the same command line with commas.The Print # command separates two or more values on the same command line (separated by a comma) with a tab character.

Print # writes an image of the data to the file, you must delimit the data yourself so it prints correctly. If you use Tab (or a comma) with no arguments to move the print position to the next print zone, Print # also writes the spaces between print fields to the file.

Advantages of Write
When using Write # to write data to a file, several universal assumptions are followed so the data can always be read and correctly interpreted using Input #, regardless of locale:

  • Numeric data is always written using the period as the decimal separator.
  • For Boolean data, either #True# or #False# is printed. The True and False keywords are not translated, regardless of locale.
  • Date data is written to the file using the universal date format. When either the date or the time component is missing or zero, only the part provided gets written to the file.
  • Nothing is written to the file if outputlist data is Empty. However, for data, #Null# is written.
  • If outputlist data is Null data, #Null# is written to the file.
  • For Error data, the output appears as #Error errorcode#. The Error keyword is not translated, regardless of locale.

To get your memory refreshed, look at the following code:

OpenW 1
Write App.Name          // "NoName"
Write CFloat(3.2)       // 3.2
Write CDate(Now)        // #2012-07-11 12:42:33
Write CBool(0)          // #False#
Write CHandle(0)        // #Null#
Write CFloat(3.2), Date // 3.2,#2012-07-11 12:42:33

' Print inserts a space at the front of a number
Print App.Name          // NoName
Print CFloat(3.2)       //  3.2
Print CDate(Now)        // 11-7-2012 12:42:33
Print CBool(0)          // False
Print CHandle(0)        //  0
Print CFloat(3.2), Date // 3.2      #2012-07-11 12:42:33

Unlike the Print # statement, the Write # statement inserts commas between items and quotation marks around strings as they are written to the file. You don't have to put explicit delimiters in the list. Write # inserts a newline character, that is, a carriage return–linefeed (Chr(13) + Chr(10), after it has written the final character in outputlist to the file.

If, at some future time, you want to read the data from a file using the Input # statement, use the Write # statement instead of the Print # statement to write the data to the file. Using Write # ensures the integrity of each separate data field by properly delimiting it, so it can be read back in using Input #. Using Write # also ensures it can be correctly read in any locale.