Burkhard's VFP Blog

Cool VFP Event Binding

2011-05-13T00:40:00.000+02:00

Version: 1.00.00 - last update: Wednesday, August 30, 2011, 14:25:00

Recently, I reviewed some of my elder VFP event binding code and stumbled upon some unknown(?) COOL behavior!

Intro

Instantiating objects from classes, calling their methods, passing (parameter) values back and forth between them, is our bread and butter business. Since VFP introduced event binding a whole new universe of possibilities arose. This post cannot cover the whole subject in detail; one has to write a book for that to come close. Thus, I am going to show you the most interesting (partially unknown!) aspects of event binding today.

What You Should Know

Well, you should have worked with VFP’s event binding. At least, you should have read about it! I’m going to discuss the following commands and functions:

BINDEVENT(oEventSource, cEvent, oEventHandler, cDelegate [, nFlags])
UNBINDEVENTS(oEventSource, cEvent, oEventHandler, cDelegate)
AEVENTS( ArrayName [, 0 | 1 | oEventObject ] )
RAISEEVENT( oEventSource, cEvent [, eParm1...] )

You should be familiar with the above commands, especially with the correct application of the [, nFlags] parameter! At least you should know the difference between nFlags:= 0 and nFlags:= 1 and you should also know the difference between that first pairing and the second set: nFlags:= 2 and nFlags:= 3.

Event binding makes it possible to extend otherwise sealed classes, even at runtime! Event binding makes your class design extendable and thus, reusable by others without touching your source code at all! Great benefits often have some drawbacks, which especially is true in case of VFP’s event binding implementation. Binding to VFP’s events is quickly learned; securely implementing custom events and handle unsolicited binding-clients the right way seems to be a little bit more challenging! Finally, binding parameterized delegates to scalar and non-scalar properties, can be regarded mastering the fine art of event binding!

A Deeper Understanding

To gain a better understanding of what’s going on we have to make clear some terms and talk about some differences, first. A lot of VFP-newbies make errors in reasoning, while implementing method code for VFP events like shown below:

Answer the following questions:
“What kind of code is the above line after we saved the form class?
Is the call to “THIS.oLstGLOBALMEM.Requery()” the Form1.Activate() event now?
Can we manipulate VFP’s form activation behavior through adding code, maybe like so:

Can we hinder VFP to activate the form through code inserted here, anyway?

The answer simply is: “NO!”

VFP’s form activate event is a simple NOTIFICATION. The code we are adding in the editor has nothing to do with handling the form activation itself! VFP has already done all that handling completely and transparently behind the scenes before passing back programmatic control to our code block above. Our code solely is a NOTIFICATION REACTION. The only reason to add custom code to such kind of VFP event is that we want some code to be executed automatically every time our form gets activated (maybe to signal the form activation to another observer instance within our framework).

There are other kinds of native VFP events. First, let’s look at the INIT() event which is a public feature of every VFP class:

Everybody knows: returning a Boolean FALSE from Init() will cancel the whole instantiation process. In terms of completing object construction, our code can be considered an addition to VFP’s internal event sequence. VFP’s Init() events are notifications as well. But, they are also EXTENDABLE. Seen from that point of view, the event acts like a program hook and our code is some kind of a POST-EVENT HOOK IMPLEMENTATION.

Finally, there is a third kind of native VFP events. One of them, the KeyPress() event, is shown below:

Code entered here may override VFP’s native implementation completely. Typically, in such a case you are using the NODEFAULT keyword to tell VFP that you are going to override it’s native behavior. You may re-enable (execute) VFP’s native behavior at any time through issuing a DODEFAULT() in your source code. Thus, I call those native VFP events OVERRIDABLE EVENTS and code added here (as long as it overrides VFP’s native behavior) is the real EVENT IMPLEMENTATION.

Let us summarize VFP’s event types:

NOTIFICATIONS are VFP post-event hooks where we can add our own REACTIONS.

EXTENSIONS are VFP post-event hooks where we can add our own IMPLEMENTATIONS.

OVERRIDES are VFP pre-event hooks where we can substitute VFP’s native behavior with our own IMPLEMENTATION.

Calling vs. Raising

An event must be raised! We neither call, nor do we raise any native VFP event implementation directly! Instead, what we do is, we call or raise our custom code added to a native VFP event. Internally, VFP treats our custom code like any other ordinary method. If you visit VFP help on BINDEVENT() you can read what is explained in case nFlag := 3 >> Call event code before delegate code. Do not trigger event (call delegate code) when simple method calls occur. VFP is able to differentiate between a “simple method call” and the “raising of an event”, which is done using the RAISEEVENT() command. Superficially, it doesn’t make any difference at all because our method code gets executed just fine in any case.

Another newbie error in reasoning is to assume, one could trigger VFP’s native behavior through raising the event. No, very sorry, but we CANNOT move the mouse over a VFP form instance by doing something like this:

RAISEEVENT(oForm1 ,"MouseMove", 10, 10)

Nothing would happen – I’m afraid, we have to use VFP’s MOUSE command further on. BTW: Reading VFP’s help file, RAISEEVENT() still is called a function there, although only returning TRUE like any other VFP procedure. Maybe some of you remember VFP’s early implementations of RAISEEVENT()better than I do! I believe version #1 of RAISEEVENT()was able to return values from the handler methods (if they had some RETURN <whatever> code implemented). That behavior was dropped in a later VFP release, because it caused some unsolvable erroneous side-effects. Nowadays, RAISEEVENT()does not return a value other than any other regular procedure does: TRUE. Thus, IMHO - RAISEEVENT()is not a function, but a command!
VFP’s help on RAISEEVENT()starts with >> You can use RAISEEVENT() to raise, or trigger, an event from a custom method. Though RAISEEVENT() applies primarily to custom methods, you can use it for raising native events and methods, too. It is true that in most cases we will use RAISEEVENT() to “ennoble” our custom methods (to become distinguishable events)!

Implementing a Custom Event

Let’s implement our own custom event to see how things work together. These are the steps we need:

Define event (create a method with or without parameters).
Optionally, implement event behavior within the event method.
Optionally, you may want to implement security as described further below.
Optionally, describe event signature and binding flag values.
Implement a trigger either using RAISEEVENT() somewhere in your code, or within a distinct trigger method.

The easiest step is the first: Define the event method and its signature. If no parameters have to be passed and you want to create a simple NOTIFICATION, just add an empty method to your class and you’re done! We already talked about the missing return value because raising an event is not comparable to calling a function (which should always return exactly one value), but more to executing a command (which never should return a value). We could argue to compensate a missing return value by passing parameters by reference (to get back some results from there). Obviously, this was “foreseen” by some joker at Microsoft, because this option was dropped completely! If we bind to an event method with one or more parameters in its signature and the event gets raised with one or more values passed in by reference, a trappable error is thrown and our RAISEEVENT()call will fail. The best alternative we have is using Parameter Objects, as objects are always passed by reference. Thus, my favorite minimal default event implementation looks like this:

PROCEDURE LogOn(toPara AS OBJECT) AS VOID
	*\\ this event gets raised when the user
	*\\ clicks the [Submit]-button on the 
	*\\ login dialog form
ENDPROC

The event source code above consists of descriptive remark lines only. The parameter object passed in toPara is a minimalistic data container object coming from a tiny factory method like shown below:

FUNCTION CreatePara(tcName AS String, tcPassword AS String) AS ParaObject
   LOCAL loEvtMsgInfo AS Object
   m.loEvtMsgInfo = CREATEOBJECT("EMPTY")
   ADDPROPERTY(m.loEvtMsgInfo, "Name", m.tcName)
   ADDPROPERTY(m.loEvtMsgInfo, "Password", m.tcPassword)
RETURN m.loEvtMsgInfo
ENDFUNC

Because there is no event behavior to implement, I am ready to implement my trigger code (which is step #5 in the above enumeration). The submit-button’s click() event is the perfect place to implement my trigger code:

PROCEDURE oSubmitButton.Click() AS VOID
	*\\
	RAISEEVENT(THIS.oHandler ,;
		"LogOn" ,;
		goFactory.CreatePara(Thisform.TxtName.Value,;
				        Thisform.txtPassWord.Value))
	*//
ENDPROC

Consuming a Custom Event

Every event handler who wants to consume our new event must bind to it using VFP’s BINDEVENT() function. Terms used, when talking about event binding, come in pairings like event source and event handler, or raise event and bind event. Finally there is a flag value used in VFP’s BINDEVENT() function to fine-tune internal signaling. To successfully establish a native VFP event binding we need two object references, as it is not possible to use an old-fashioned procedure as the event handler! (BTW: There is a VFPX project called “VFP2C32”, maintained by Christian Ehlscheid, that gives you the ability to use procedural delegates – but only for Win-Event binding.) In any case, one object is called the source of the event, the other the handler of the event. There are other naming pairs like publisher and subscriber often used in COM documentations, or signal and slot used by Nokias Qt (C++ IDE). Anyway, the event source has a public event (-method or -property) we must know by name and what signature is used when the event is raised by the trigger, so that we can bind our event handler object to it. Our event handler object must have a corresponding delegate method (no properties - only methods - are allowed as delegates) with the method signature that has at least enough parameters to receive all values passed in by the RAISEEVENT() trigger.

Sidekick: Property-based Event Binding Part I

Keep in mind: When binding to a PROPERTY-based event, our handler should be a parameter-less delegate method. At this moment, it doesn’t make much sense to use a delegate with one or more parameters, because a simple value assignment to an event-bound property CANNOT lead to a signature mismatch. There are two other things to keep in mind about property binding:

Property binding can be compared to implementing a PropertyName_Assign() method. The delegate gets called every time some value is stored in the so decorated property, just like any _ASSIGN() method is triggered. Read access NEVER leads to delegate invocation.
Executing a RAISEEVENT()on a property causes nothing else but a re-assignment of the current property value. In other words, the actual property value stays unchanged. Therefore, oForm1.HEIGHT = oForm1.HEIGHT can be considered to be internally treaded like a “simple method call”, whereas RAISEVENT(oForm1, “HEIGHT”) internally is recognized as the “event of property value re-assignment”.

Most of this is theory only, taken from VFP’s help files! You will get more comprehensive insights later in this post (in property-based event binding part II below).

Generic Events and Handlers

Even carefully reading of VFP’s help may lead to some misunderstanding! This is what is written about the delegate parameter of BINDEVENT():
cDelegate:
Specifies the method, or "delegate", that handles the event for oEventHandler. The delegate method must have the same parameters as the event specified in cEvent. You can call the AEVENTS( ) function to retrieve an object reference to the event source. If the delegate method does not have enough parameters to handle those passed by the event, Visual FoxPro generates an error.

The underlined sentence above may make you believe, that both, the event’s and the delegate’s signatures must be identical. This is not true! Only the last sentence fully tells the truth: the handler’s delegate signature must be capable to receive all parameters that were passed in during event invocation. This is nothing really new. We all have seen parameterization errors stemming from method calls in cases a caller tried to pass more parameters than there were implemented. On the other hand, calling any method passing less parameters than the implementation has, does work like a charm, at least the invocation. The same is true while raising an event. Under the hood, VFP does not draw a distinction between event methods and other methods when it comes to parameter passing. Thus, it is absolutely legal to create a set of generic event handler methods that can be bound to any (generic) event method! Keep in mind: VFP’s maximum number of parameters that can be interchanged during all kind of calls is #26, which is more than enough, IMHO. This capacity also is the upper limit of VFP’s RAISEEVENT()command. If you really need more, switch to a parameter object!

A “Generic” Event

An event cannot be generic in the truest sense of the word! Only the event method signature can be generic, in that the method accepts all possible 26 input parameters!

Let’s create a form and add an event method with such generic signature. Next, we will add some event behavior (just for initial testing). The final result looks like so:

Lets DO the form and invoke the EvtSendOut() method using a regular method call from VFP’s command window:

m.testform2.EvtSendOut("What","a","difference","a","day","makes!")

The result, as expected, is shown below:

Now, raise the EvtSendOut() method as a custom event typing the following line of code into VFP’s command window:

RAISEEVENT(m.testform2, "Evtsendout", "What","a","difference","a","day","makes!")

Again, the result is the same, as shown below:

You may play with different parameterizations of the RAISEEVENT() command. As long as you do not try to pass more than 26 parameters, all invocations will be executed successfully.

Let’s prove that we cannot raise a custom event passing in a parameter by reference. With the test form still running type the following code lines into VFP’s command window and execute them one by one:

x = "Hallo"
m.testform2.Evtsendout(x)
m.testform2.Evtsendout(@x)
RAISEEVENT(m.testform2, "Evtsendout",x)
RAISEEVENT(m.testform2, "Evtsendout",@x)

Only the last command will throw an exception, like shown below:

It is the “Missing operand” error #1231. Well, “Missing operand” sounds strange indeed, but there is an error – as I promised :-)

A “Generic” Delegate

What’s true for the event is true for the delegate, too: A delegate cannot be generic in the truest sense of the word! Only the delegate method signature can be generic, in that the method accepts all possible 26 input parameters! Let’s complete this first test-drive. Initially, we filled our event (method) with code that would be better placed in a delegate (method). Let’s add such a delegate to our form and copy the whole implementation to the new delegate. Keep only the LPARAMETERS statement in the event. The intermediate result should look like this:

Again, we will use VFP’s command window for manually binding and triggering. Save the form and create two named instances like so:

DO Form c:\<your path>\testform2.scx NAME Sender
DO Form c:\<your path>\testform2.scx NAME Receiver
m.Sender.Caption = "Sender"
m.receiver.Caption = "Receiver"

Now it is time to link the receiver to the sender using an appropriate BINDEVENT() command. Our first binding does not use a special nFlags value. VFP defaults to nFlags = 0 in that case.

? BINDEVENT(m.sender, "EvtSendOut", m.Receiver, "OnSendOut")

Now, trigger the event on the sender form like so:

RAISEEVENT(m.sender, "Evtsendout", "What","a","difference","a","day","makes!")

The delegate code of the receiver form executes and echoes the text out on the currently activated form:

Changing the parameter count (within the valid boundaries) executes just fine! Try the following, if you like:

RAISEEVENT(m.sender, "Evtsendout", "What","a","difference","a","day","makes!", "Come", "on", "Baby!")

Keep both forms open and read ahead – we will reuse them in the next chapter.

Benefits of Using Generic Signatures

Using generic signatures with your events and delegates frees you from keeping track of parameter count changes, which otherwise must be kept in sync over three different places (event, delegate and trigger) if you raise the parameter count used by the trigger. This does not mean that you must not keep your implementations in sync with the parameters coming in :-) Keep in mind: Always placing 26 LPARAMETERS in your event-related methods slows down program execution slightly, because VFP has to create 26 local variables each time the methods must be invoked. I’m using my own special breed of generic method signatures within my frameworks and never encountered any performance hits, because I reduced the parameter count of my framework class methods down to three. The first parameter is the name of the method/service, the second is a parameter object which may take as many parameter properties as needed, the last parameter is the object reference of the sender.

Implementing a Custom Event-Handler

We have seen that calling a method must not differ from raising it, seen from the view-point of someone who triggers the execution in one way or the other. A noticeable difference may only appear for the event handler side of the binding. Using nFlags values of 2 and 3 in the BINDEVENT() command only invoke the event handler’s delegate when the event was triggered using RAISEEVENT(). Using nFlags values of 0 and 1 in the BINDEVENT() command additionally also invoke the event handler’s delegate when the event was triggered using a regular method call. Check it out! You can do that with only two lines of code if the above 2-forms test environment is still set and running:

UNBINDEVENTS(m.sender)
BINDEVENT(m.sender, "EvtSendOut", m.Receiver, "OnSendOut", 2)

With the nFlags value set to 2, try to invocate the event handler’s delegate through triggering the event using a simple method call like so:

m.sender.EvtSendOut("EvtSendOut", "What","a","difference","a","day","makes!", "Come", "on", "Baby!")

Nothing happens – as I told you!

After all, IMHO, only BINDEVENT() commands in code using nFlags values of 2 or 3 should be legitimate for today’s event binding implementations, which must not mean that there are no good reasons for using nFlags values of 0 and 1. If one has to bind to legacy methods that were realized a long time ago (when event binding still was a foreign word for VFP developers), one is forced to use nFlags values of 0 or 1 while binding to methods that never will be raised but always gets called (the old-fashioned way). In addition to that, there are some native VFP “events” (like GotFocus(), LostFocus(), InteractiveChange(), and ProgrammaticChange()) that are treated as method calls internally by VFP, so that we are forced to use a nFlags value of either 0 or 1. My suggestion always is: NEVER bind to VFP’s native properties and methods/events directly, but implement your own custom event system/scheme. I will show you my own (more sophisticated:-) implementation in a future posting…

The table below shows all four possible values (bit flag values) counting the bits starting with #0. The “trigger all” row represents both bit#0 states, the “trigger only raised” row shows the two bit#1 states. Both bits are OR-combined. The four resulting values are printed in bold within the matrix. Just to make this part of my writing complete: Bit #3 of the nFlags parameter is used to prevent recursion in case of Window Message Binding (which isn’t discussed in this posting).

nFlags values	invoke delegate *before* event	invoke delegate *after* event
Bit #0 >> trigger all	0	1
bit #1 >> trigger only raised	2	3

Seen from my personal point of view (as a framework developer), there are many different objects at runtime lurking around to bind to my events. I divide these event handler objects into two groups: one group want to process parameters BEFORE my own implementation processes them, the other (lazy:-) group can wait until my event code is finished, receiving the parameters AFTER my implementation returns.

Sidekick: Property-based Event Binding Part II

Binding to properties makes it even easier to understand what’s going on under the hood: Those delegates that were bound to a scalar property with nFlags values of 0 or 2 can only show the old property value (before the assignment takes place), delegates that were bound to the property with nFlags values of 1 or 3 will always show the new property value (the “after-assignment-value”). The following listings show us two generic property-delegates. You may add them to our form before test-drive them. Bind both delegates to a property like shown below. BTW, the method signature of a regular property-delegate always is empty because we do not need any parameters, as long as we are solely assigning new values. I underlined the word “need” bold italic because it is important to stress this for a good reason:

we do not need any parameters, but it is not forbidden to implement some, as I will show you later in this chapter!

This is the test code we will run next:

ADDPROPERTY(_SCREEN, "nTest")
DO Form c:\<your path>\testform2.scx
BINDEVENT(_Screen, "nTest", m.testform2, "OnPropertyBefore")
BINDEVENT(_Screen, "nTest", m.testform2, "OnPropertyAfter", 1)
_Screen.nTest = 1
RAISEEVENT(_SCREEN, "nTest")

You may also want to implement some ”laBindings[3]“– test code like the following two listings show:

PROCEDURE OnPropertyAfter() AS VOID 
	*\\ a generic property-event delegate 
	LOCAL ARRAY laBindings[3] AS Variant 
	LOCAL lnCount AS Integer 
	*\\ AEVENTS( ) returns a three-element array containing 
	*\\ an object reference to the current event source, 
	*\\ the name of the triggered event, 
	*\\ and how the event was triggered. 1 - RAISEEVENT() 
	*\\ 2 - Method call 
	lnCount = AEVENTS(laBindings, 0) 
	IF m.lnCount > 0 
		LOCAL eValue AS Variant 
		WITH laBindings[1] 
			eValue = EVALUATE("." + laBindings[2]) 
		ENDWITH 
		? "New value is " + TRANSFORM(m.eValue) 
	ENDIF 
ENDPROC

PROCEDURE OnPropertyBefore() AS VOID
*\\ a generic property-event delegate
LOCAL ARRAY laBindings[3] AS Variant
LOCAL lnCount AS Integer
*\\ AEVENTS( ) returns a three-element array containing 
*\\		an object reference to the current event source, 
*\\		the name of the triggered event, 
*\\		and how the event was triggered. 1 - RAISEEVENT() 
*\\						 2 - Method call
lnCount = AEVENTS(laBindings, 0) 
IF m.lnCount > 0
	LOCAL eValue AS Variant
	WITH laBindings[1]
		eValue = EVALUATE("." + laBindings[2])
	ENDWITH
	? "Value assignment for " + laBindings[2] + " triggered!"
	? "Old value is " + TRANSFORM(m.eValue)
ENDIF
ENDPROC

VFP returns a “trigger type”-value (0-System, 1-RaiseEvent, 2-MethodCall) in the third array element of the local array “laBindings”. Okay, you may think, all this is pretty straight forward and matches VFP’s help documentation one by one. But, this is not true! There are some important points: 1st, VFP’s event binding related help is not correct in some places and 2nd, some helpful things are not mentioned at all.

1a.) You can read about the AEVENTS(arrayname,0) version in VFP’s help file: “The third array element indicates how an event was triggered. If the event is a property, this value can be 1 or 2. The value is 2 if the property is set or assigned.” Simply, this is not true! In our above example laBindings[3] never will hold the value 2 (two). During my testing sometimes I got a zero or the value one but never a two! Thus, the correct statement must be: “The third array element indicates how an event was triggered. If the event is a property, this value can be 0 or 1. The value is 1 (= RAISEEVENT()) if the delegate was triggered using the RAISEEVENT() function! In all other cases the third array element is 0 (= System).”

1b.) Assigning a value to any scalar property with bound delegates always fires all delegates! In other words: You may bind to a property with a nFlags-value of 2 or 3 which would suppress delegate execution in case of a simple method call when applied to a VFP method. Later, when assigning a value to the property, you might expect that the delegates will not be called. Sorry, but that doesn’t work for scalar values! This leads to the next oddity:

1c.) Assigning a value to any non-scalar property (to an array property) just works as expected – well, almost! Instead: An array value assignments do not trigger bound delegates at all! At least: doing a RAISEEVENT() on an array-property fires ALL bound delegates just like described in 1b.) above!

Let’s create some examples to make things a little bit clearer:

Given one source- and one target object named “oSource” as the event source object and “oHandler” as the event handler object, let us define two properties on the source object: “oSource.cProp” and “oSource.aProp[1]”, so that we have one scalar and one non-scalar property at our disposal. Now, let’s add two _Assign() methods for both properties: “oSource.cProp_Assign()” and “oSource.aProp_Assign()”. Finally, let us add four delegate methods called “delegate0()” to “delegate3()” to our handler object.

Now, we can run code like this from VFP’s command window:

oSource = NEWOBJECT("cSource", "testlib.vcx")
oTarget = NEWOBJECT("cTarget" , "testlib.vcx")
*\\ bind to the scalar property
BINDEVENT(oSource, "cProp", oTarget, "Delegate0", 0)
BINDEVENT(oSource, "cProp", oTarget, "Delegate1", 1)
BINDEVENT(oSource, "cProp", oTarget, "Delegate2", 2)
BINDEVENT(oSource, "cProp", oTarget, "Delegate3", 3)
*\\ now bind to the non-scalar property
BINDEVENT(oSource, "aProp", oTarget, "Delegate0", 0)
BINDEVENT(oSource, "aProp", oTarget, "Delegate1", 1)
BINDEVENT(oSource, "aProp", oTarget, "Delegate2", 2)
BINDEVENT(oSource, "aProp", oTarget, "Delegate3", 3)

The first version of our delegate code is almost identical in all event handler methods . Is echoes out the three AEVENTS(array,0) array values.

LOCAL ARRAY laEvt[3]
IF AEVENTS(laEvt,0) > 0
	? "Handler 0 ---------------------"
	? "laEvt[1] = " + TRANSFORM(laEvt[1])
	? "laEvt[2] = " + TRANSFORM(laEvt[2])
	? "laEvt[3] = " + TRANSFORM(laEvt[3])
ENDIF

You only have to vary the handler number. Replace “Handler 0 ----“ with “Handler 1 ----“, “Handler 2 ----“, and “Handler 3 ----“ in the four different delegates.
Now, add some echo statements to the cProp_Assign() hook like:

LPARAMETERS vNewVal
? "cProp_Assign() before assignment - value is '" + TRANSFORM(THIS.cprop) + "'"
THIS.cprop = m.vNewVal
? "cProp_Assign() after assignment - value is '" + TRANSFORM(m.vNewVal) + "'"

and for the aProp_Assign() hook and like:

LPARAMETERS vNewVal, m.nIndex1
? "aProp_Assign() before assignment"
IF ISNULL(m.nIndex1)  && user didn't pass in a subscript
	?? " - value is '" + TRANSFORM(THIS.aprop) + "'"
	THIS.aprop = m.vNewVal
ELSE
	?? " - value is '" + TRANSFORM(THIS.aprop[m.nIndex1]) + "'"
	THIS.aprop[m.nIndex1] = m.vNewVal
ENDIF
? "aProp_Assign() after assignment - value is '" + TRANSFORM(m.vNewVal) + "'"

Now we can assign a value e.g. to the scalar cProp property: oSource.cProp = "Hello World!" and watch the sequence that gets echoed out to VFP’s desktop:

The first line is generated by the first ? "cProp_Assign() before assignment - value is '" + TRANSFORM(THIS.cprop) + "'" expression.
During execution of the second statement: THIS.cprop = m.vNewVal all four event handlers are raised, which generate the “Handler x ------------------------------“ … output lines, one after the other.
Finally, the second ? "cProp_Assign() after assignment - value is '" + TRANSFORM(m.vNewVal) + "'" expression is executed.
As you can see, the handlers #1 and #3 are definitely firing AFTER the value assignment, whereas handlers #0 and #2 only can show the initial empty string value. Anyway, all four handlers fired!

Now let’s have a short look what happens if we assign a value to the (non-scalar) array property like so: oSource.aProp = "Hello World!" and watch the sequence that gets echoed out to VFP’s desktop:

As you can see, no event handler gets called at all!

1d.) RAISING a scalar property like so: RAISEEVENT( oSource, "cProp") does NOT trigger an existing _Assign() method, because internally VFP does not execute a real self-assignment, but only invokes all bound delegates. This produces the following output:

The output shown above is the same when we are raising our non-scalar array property! Thus, we can state that VFP’s property-raising behavior is consistent for both property types (scalar and non-scalar ones)!

2a.) VFP’s help file is missing some interesting things that should also be known! What’s about resetting a property to the class-default using VFP’s ResetToDefault() method?
This is what will happen, if you issue the following commands:

oSource.ResetToDefault("aProp") or 
oSource.ResetToDefault("cProp")

They yield in the following output ( I added this: ? 'ResetToDefault("' + m.cProperty + '")' to the form’s ResetToDefault() method):

When resetting the form’s non-scalar .aProp[] property only a single

is echoed out. The two most interesting parts to remember are:
1st) Resetting a (non-scalar) array property neither raises an event handler nor does it call an existing _ASSIGN() method!
2nd) On the other hand, resetting a scalar property does it all, but with one interesting difference: all event handlers, as well as the _Assign() method call itself are invoked AFTER VFP’s internal ”resetting process” has finished work! You can see above that the property value already is empty when the Assign() method call (followed by the event handler invocations) takes place. What exactly is going on while resetting an array property cannot be monitored due to the 1st limitation.
3rd) One final thing to mention is, that trying to reset an array property back to it’s class default using code like: .ResetToDefault("array_property_name") is useless! Neither a changed array dimension will be restored, nor will the remaining array elements be set to .F. again. This is the default behavior documented in VFP’s help file.

The following section is for all VFP PROs (who think they know all and everything ;-)

2b.)
We can bind any event handler to a property. Better said, we can parameterize a property-event handler without limitation (okay, within VFP’s maximum parameter count limit). The best is jet to come: We can raise a property with as much parameters as we want (within VFP’s maximum parameter count limit), as long our delegate is able to receive/handle the parameter values! You are not that exited? Wait, better think twice!

VFP’s AEVENTS() function is a nice to have thing, when we need to find out what the source of the event was. Creating a local 3-element array that gets filled with the appropriate information first, sometimes sounds like creating to much overhead. At least in tight loops raising slow delegates very often can become a speed-bottleneck at runtime. Naturally, after having mentioned that we can bind any kind of parameterized delegate to a property, it is easy to guess, what comes next: Let us use parameterized delegates on properties!

The diagram below seems a little bit confusing at first sight. Thus, let me explain what it should depict. To keep things as simple as possible at the beginning there are 4 object in our example: one form (on the GUI layer) with two interface objects (at the wiring layer) and one manager/controller object (in the business/system layer).

A reference of each form interface object will be stored in the form (the thick black lines). The form’s Resize() and Moved() events may implement trigger code like the following (a reference to the “Position&Size” interface object is stored in the form’s “oInterfacePosAndSize” property:

*\\ Trigger code in the form's MOVE() event
RAISEEVENT( THIS.oInterfacePosAndSize,;
		"Position",	;
		THIS,		;
		THIS.Left,	;
		THIS.Top,	;
		THIS.Width,	;
		THIS.Height	)

and

*\\ Trigger code in the form's RESIZE() event
RAISEEVENT( THIS.oInterfacePosAndSize,;
		"Size",	;
		THIS,		;
		THIS.Left,	;
		THIS.Top,	;
		THIS.Width,	;
		THIS.Height	)

The cool thing about these constructs is that they run without errors even if there is no delegate attached/bound. In other words: we can set up a series of EMPTY-based interface objects like shown above, link them to their implementation instances and bind triggers and delegates to their properties. You can move such a form and resize it as you like, there will be no delay. The form instance behaves absolutely “normal”! Firing triggers that raise events on unbound properties is a totally transparent process.

Now, what’s next? Okay, our form layout controller instance is very interested in what users are doing with our forms. But, instead of holding/storing a form reference (working directly with the public interface of each form), the form layout controller only binds his delegates and triggers to the properties “Position” and “Size” of the form’s interface object. The signatures of the delegates are shown below:

*\\ Handler signature in the form layout controller's OnPosChange() delegate 
LPARAMETERS oSender AS Object,	;
		tnLeft AS Integer,	;
		tnTop AS Integer,	;
		tnWidth AS Integer,	;
		tnHeight AS Integer

and

*\\ Handler signature in the form layout controller's OnSizeChange() delegate 
LPARAMETERS oSender AS Object,	;
		tnLeft AS Integer,	;
		tnTop AS Integer,	;
		tnWidth AS Integer,	;
		tnHeight AS Integer

Now, moving or resizing the form will cause invocation of the bound delegates of the layout controller. Of course, you have to implement something useful there. I leave that to your imagination. One thing should also be mentioned: Using parameterized event raising on properties passing a self reference as one of the parameters frees the event handler from using VFP’s AEVENTS() function to retrieve such a sender reference!
Additionally , you may want to shorten the signature of your “raise-events”. Two parameters are enough: the sender reference and a parameter object. This is just the way most of .NET’s event binding works.

What we have now is a ultra-lightweight EMPTY object containing as much scalar properties as we need. We only need to know the name of the property, because the property only has to exist – the property value doesn’t matter, it is irrelevant. The property can be seen as some kind of binding-handle: a unique address we can bind our handlers to and raise our events. Our delegate implementations should test then for a parameter count > 0 to reassure the property-event was RAISED and not triggered by a simple value assignment, like so:

*\\ Handler code in the form layout controller's OnSizeChange() delegate 
LPARAMETERS oSender AS Object,	;
		tnLeft AS Integer,	;
		tnTop AS Integer,	;
		tnWidth AS Integer,	;
		tnHeight AS Integer
*\\ only process invocations stemming from a RAISEEVENT()
IF PCOUNT() = 0
	RETURN
ENDIF
*//

More benefits

The technique I presented here is based on using EMPTY-based objects to setup some kind of generic event binding. Sure, you can use other “full-blown” VFP classes instead to add more functionality to your interface objects. In my own FoxQuill framework I call these extended interfaces “smart interfaces”, because they are able to host contracts to validate incoming, as well as outgoing parameter values. This is my way to completely separate inter-object messaging/communication from function implementation.

Passing ultra-lightweight interface objects around saves you from spreading your real object references all over the place. Dangling references are almost unknown to my personal framework, since I’m using these binding-proxy objects. Another benefit is: now we can split our objects’ interfaces and group them on a logical basis: one set representing queries, another set represents commands, and two others hold events and exceptions.

Finally imagine: you will be able to pass all those interfaces into an environment (I call mine “The Matrix”:-) where some generic (data-driven) mechanism links logical children to their parents and/or service-providers to their service-subscribers. That way, all your (implementing) objects can be stored in one place (I call mine “The Construct”:-) and the inter-object communication system can be set up (even dynamically at runtime). Implementing security related message redirections or adding some extensions to an existing workflow has never been easier to realize!

Protect Your Events

Let’s assume there is a password dialog object asking your end-user to enter her name and password in two textboxes. If the password dialog class is one of your framework goodies, maybe your way of returning the user name and password is based on event binding. Thus, your dialog class may have an event called Logon(). You are raising the Logon() event when the end-user clicks the login-button on your dialog, passing an EMPTY-based object containing to fields: UserName and UserPass. Let’s further assume that password encryption and verification is part of another business-layer and not implemented in your GUI (bravo!). Then, there is a short timeframe, since you’ve raised Logon(), where the password exists unprotected in a data capsule that may be intercepted by anyone who had access to your login dialog before! Shure, there are better ways to pass sensitive data in such a case, but this is only an example!

What Do We Need

We need a little VFP project we can use for our experiments. Let’s set up a tiny login dialog class and a second class representing the junior version of a Password Manager just to have two instances between which we can establish our binding.

Finally, let’s build a spy class that tries to monitor the login dialog’s Logon() event to intercept and catch the user’s name/password combination.

Securing Events

Back to the golden thread! Let’s use the form we already created for our first test-drive. I saved it under a new name “LOGIN.SCX”. Below there are two screenshots showing the login form’s GUI layout in development mode and at runtime:

Clicking the [Submit (ENTER)]-button executes the following code:

During form’s initialization I added a data object like so:

Pressing ESC or clicking the [Abort (ESC)]-button executes the following code:

My event method .EvtSendOut() stays untouched. I added a new .Trigger() method from where .EvtSendOut() is raised or called, which depends on the 3rd parameter that can be passed into my .Trigger()method: 1 – RAISEEVENT() | 2 – Method call. The 4th parameter of my .Trigger()method passes security-related information. I decided to decode the security test type numbering so that it is easy maps to VFP’s nFlags values. The table below tells you about the integer mapping:

value	description
0	no security testing at all (just pull the trigger :-)
1	unbind all event handlers that are using nFlags = 0 for their delegate bindings
2	unbind all event handlers that are using nFlags = 1 for their delegate bindings
4	unbind all event handlers that are using nFlags = 2 for their delegate bindings
8	unbind all event handlers that are using nFlags = 3 for their delegate bindings
16	repeat check (to protect against timer-driven spy-ware)

Needless to say, the bit values from above can be combined to “filter out” more than one group. If you want to block all delegates bound with nFlags values of 0, 1, and 2, just pass a seven (7) to the .Trigger()method. Naturally, there is no native VFP way to filter out established bindings. Thus, we have to get rid of the unwanted bindings using old-fashioned “hammer-style”: Just Unbind Them :-) Of course, good spy-ware would try to re-establish it’s “wiretapping”. The only way to achieve that successfully, is using a timer. Therefore, I added the option (add +16 to the 4th parameter) to set a marker flagging that the security test is no longer optional!

The screenshot above shows my test environment with actually 4 running spy instances. Each spy has bound itself to the login form (that is the caption- and borderless child window inside the Password Manager) with a different nFlags value (to proof that my protection scheme really works as expected) My login form’s trigger method was called from the [Submit]-button allowing only delegates bound with nFlags = 3 to stay linked, because (as I mentioned before) the guys with nFlags 0 or 1 are no real event handlers today (IMHO)! The rest of the guys has to wait, until I finish processing – thus, they must bind with AFTER INVOCATION := 3! This gives me room to process the unprotected login data (you can see it below: the new caption of my Password Manager form displays it). Naturally, before returning from my password manager, I changed the originally entered name and password to some less valuable text ;-) which was captured by spy #4 (numbered from top to bottom on the screen shot). Have a good time with that, SPY#4!

Where is the Beef?

<<< Here it is! Use this download link to get all sources to play with…

Final Thoughts

Native event binding is one of the most useful features that were added to VFP over the time! To be honest, I started developing my own VFP framework not until event binding was introduced! Even though there are many little bumps on the floor (especially, when applying event binding to VFP’s native properties), up to now, I never found another development environment that gave me more freedom to create extraordinary specialties with ease!

Hierarchical Table Order (Part I)

2011-05-12T11:09:00.000+02:00

Version: 0.01.70 - last update: Wednesday, August 30, 2011, 14:35:00 (page links updated)

All you have to know about sorting table data hierarchically

Intro

When I implemented my first version of a native VFP TreeView control – just to see if it was feasible – I created the controlling driver table the typical “at least 2-columns” way. You still can download that outdated first try from here – just in case you want to peep at the table structure in question :-) After many, many hours of testing I found a couple of neat solutions to master all speed bottlenecks I encountered during test-driving my first VFP TreeView results. Today, I like to present to you one of the most interesting basics: how to sort a DBF-table hierarchically on only one column’s data WITHOUT loosing to much speed!!!

Hierarchical data - abstract

Some guys out here, even profs of computer sciences, claim that any set(s) of items can be organized hierarchically. Almost all taxonomies, numeric or non-numeric ones, have one thing in common: a one to many relationship between their members, spanning a tree-like structure stemming from one shared root element.

Hierarchies – concrete

Looking at objects at runtime, even during design-time while using “instance programming” in VFP, we immediately notice that any object has its unique identity and at least one reference path through which we can access its public members. Let’s have a look on a pretty common example showing how to print out the content of a VFP application’s textbox:

? m.goApp.oFormManager.Items(“AddressForm.1”).oPgfMaster.oPage1.oCntLeftPane.oTxtFirstName.Value

Nothing extravagant so far. So, what do we have here? There seems to be a public variable called “goApp” pointing to a global application object. Obviously, the application object contains some kind of form manager object, through which we can retrieve a form reference. In this case it is one of our address entry forms, from which a reference was stored in the form manager’s collection using a key value “AddressForm.1”. On this form there is a page frame oPgfMaster with a page oPage1 containing a VFP container object oCntLeftPane that holds the textbox oTxtFirstName we are looking for. Wow, finally we hold our textbox reference; from there we can print out the content of its value member. Well, I said it already, nothing special so far.

Let’s map this concrete implementation snapshot to the more abstract description: the root element of our reference path is our global reference m.goApp. From there we start walking the reference path down to our textbox object. There may be more than one textbox named oTxtFirstName in our application at the same time (especially if we’ve enabled multi-instance editing), but NOT inside the parent container named oCntLeftPane – the one that resides on oPage1 of oPgfMaster of .ITEM(“AddressForm.1”) managed by our app’s FormManager.
That said, everybody should understand what OBJECT IDENTITY is now. Every object has its own distinct and unique identity. In addition to that, as long as everything works flawlessly, there should be at least one reference path (like the one shown above) through which we are able to access each object individually. What we also see is, that the taxonomy tree spans from left to right. In other words, the one to many relations are written from left to right along the reference path: the form manager has many forms to manage, a form may contain more than one (top-level) page frame, a page frame usually has more than one page on it, and so on. Whereas every child can only belong to one parent at a time – at least, when it comes to real containment (in VFP). In other words: We cannot ADDOBJECT() a new class instance to more than one parental container object. In contrast to that, it is possible to add an object’s reference to more than only one other object through storing the reference to a property like so:

goApp.oCustomObjects.AddObject(“oMainForm”, “MyMainFormClass”) && add object into real container

loForm = goApp.oCustomizations.oMainForm && retrieve a local working copy of object reference

goApp.oFormManager.ADD(m.loForm, “AddressForm.1”) && a VFP collection is no container!

oApp.oSecurityManager.oMainForm = m.loForm && loose coupling only

and so on.
Line #4 shows how some security manager gets its main form reference. This reference assignment results only in loose coupling. This is no real containment-ship! Best proof: our main form has NO THIS.PARENT reference (to the security manager!) BTW, even when we use the ADD() method of the form manager collection, like shown on line #3 above, VFP internally does not establish a real containment there! VFP’s collection is no real container class but – well – a collection :-) Only on line #1 above, during instantiation, we added the form object to our custom container instance as a real child.

That said, we can recap that any VFP object reference used as a variable can be assigned many times to many different objects’ properties. In contrast to that, the object itself can only be instantiated once by another parent container class instance using ADDOBJECT() or NEWOBJECT(). I name this kind of parent objects (which references can be retrieved from within any child’s method using THIS.PARENT) the REAL PARENTS or short the CONTAINERS. All other objects holding references may only have some kind of logical parental relationship and therefor are called LOGICAL PARENTS! Again, there is no native support for logical parent-ship in VFP, only containment-ship is fully implemented!

A Short C# PEEK

.NET languages, like C#, don’t have neither functionality, nor class methods comparable to VFP’s THIS.ADDOBJECT() or THIS.NEWOBJECT(). You can instantiate any GUI control just the way you would do it in VFP with non-visual classes. Making a GUI control instance visible to the user is a simple act of adding the control’s reference to some form’s controls collection. Simulating the procedure in VFP would look like so:

loTextBox = CREATEOBJECT(“MyTextboxClass”)
loMainForm.Controls.ADD(m.loTextBox)

In .NET every container has a controls collection – just like VFP – to which a child object (reference of a class instance) can be added dynamically.

Hierarchies – a General Approach

The only nice thing about long, descriptive reference names is, that most of the tokens we are using there are (more or less) easy to memorize. Even if I did not write the above code myself, I am still able to grasp the idea where to go to get the searched first name value. One of the downsides of descriptive names is that a computer program is not able to deal with the deeper sense transported with the names, like humans do. VFP tokenizes the names and stores them in an internal table (go and Google for VFP’s NTI – name table index entries). There is not much more you can do with them, but search for existence (e.g. using PEMSTAT()). Well, you can setup a (complex) naming convention schema if you like but you have to write all of the necessary rule parsers and all the other weird stuff to enforce it on your own. Adding another semantic class to VFP’s variable- and property names introduce a whole new universe of troubles to solve.
Thus, my proposal is pretty different – I say: “Stop using object names!”

No, I do not mean “stop using names at all” but only in the first place! Let me show you how the textbox object’s value example above may be written within my FoxQuill framework:

? _GlobMem(“1.102.1.15.1.4.1.2.23.”).Value

Okay, you’re right, that looks pretty cryptic! But, using some custom intellisense functions make the whole thing as clear as any “verbose” name approach. The idea behind my notation is, to substitute human readable reference names with a very simple to understand enumeration schema! These are my basic rules:

Every class instance (object) has a unique (running) number that makes it distinguishable from all other sibling objects at the same level (of containment).

Object numbering starts with <1>. (All <0>-based object references are reserved for internal use!)

All objects exactly have at least one logical parent. There can only be one start-point object that must not have any logical parent (the root).

The reference path to any object is written using n-dimensional array notation. (In VFP we have to use strings for that.)

Relation rule #1: Child numbers are written next to their logical parent IDs on the right side, separated by a dot.

Relation rule #2: Sibling objects have the same logical parent string and differ only in their own running number.

Let’s look at an example to make things a little bit clearer:
There’s a form with a container grouping a label and a textbox: oForm1.oCntFirstName.oLblFName and oForm1.ocntFirstName.oTxtFName

Let’s say that the form is the root object in this example. Then there are the following VECTOR expressions:

Form Vector	>>	“1.”
Container Vector	>>	“1.1.”
Label Vector	>>	“1.1.1.”
Textbox Vector	>>	“1.1.2.”

I named my “numbered reference paths” vectors. Every vector carries some implicit information:

It points to exactly one object, the so called endpoint object (the endpoint). Thus, it may be used as a unique identity descriptor for that endpoint!

It describes the parental hierarchy (the containment path) from the root to the endpoint.

Each number within a vector expression (separated by a dot) is called a dimension. Dimensions are enumerated from left to right.

The dot-count of a vector expression reflects the vector’s dimension width := lnDW = OCCURS(".", Vector)
In our example above the textbox vector has an overall dimension width of <3>.

If we want to add a child to any object (even to non-containers!) we simply add the child to the object’s child dimension.

Let’s look at another example. Let’s say, we want to add some new controls to our form above. This was our form’s vector: “1.”
Now, let us add a PageFrame along with the existing container (at the same containment level). This is the vector expression of our new PageFrane: “1.2.”
Next, let us add three pages to the our PageFrane. These are the vector expressions of our new Pages: “1.2.1.”, “1.2.2.” and “1.2.3.”
Finally, let us add a container with another label and textbox to the 2nd page of our new PageFrane.
These are the corresponding vector expressions: “1.2.2.1.” (the container), “1.2.2.1.1.” (the label) and “1.2.2.1.2.” (the textbox).

Now, the hierarchical object relations should look like in the image above. Naturally, we could have used named references as well:
? oForm.oPageFrame.oPage2.oContainer1.oTextBox1.Value is the same like this: ? oConstruct(“1.2.2.1.2.”) given that there is some collection-based object named oConstruct that holds a keyed reference to our textbox instance.

More to come

There are many more things to talk about when explaining “name-less” object reference constructions in-depth: how to maintain references using keyed collection, or how to organize (re-)numbering in case of object deletions. I will describe those different aspects pretty soon in later postings. We will talk about the so-called “zero-nodes” (e.g. “0.0.0.0.0.”), you will hear about a generic “inter-object messaging” system built into an object collection I named “the Matrix”). Finally, I will show you how simple otherwise complex object maintenance tasks can be realized if one uses a collection-based class instance storage (I named mine “the Construct”)… (“The blue or the red one, Nero?” ;-)

Hierarchical data – The Solution

The screen shot above shows a TreeView which displays all items sorted correctly. Now, lets create a VFP free table to type in some test data. The outcome could look like the screen shot below:

At this early stage, the table has only one VARCHAR (binary) field called Vector which is 240 characters long. I like the VARCHAR field type, because there are no trailing blanks that have to be removed every time when fetching table data into memory. I think of VARCHAR as a regular CHAR field with an implicit RTRIM() functionality. BTW, be aware of the following: If you change a CHAR field to the VARCHAR field later, any data that has been already entered will retain its trailing spaces. An example: Maybe you have a table with a column named Clastname (maybe a C(80) field). After 500 record were entered you decide to change your Clastname field to the new VARCHAR type V(80). After that, another 500 address records were entered. Now, running through all 1000 records showing the effective content length of your Clastname field like so: ? LEN(Clastname) will show you, that the first 500 records all still print out > 80 <! Only the newly entered 500 records print their real “RTRIM()ed” varchar-lengths!

Thus, after changing an existing CHAR field containing data(!) to VARCHAR you should run a REPLACE ALL fieldname WITH ALLTRM(fieldname)ASAP!

The screenshot above shows us the non-ordered list of entries (their so-called chronological ordering). Now, lets add an index and activate it like so:

Adding a regular VFP index on the Vector column does not result in correct hierarchical sorting. As we can see, the records starting with “100.2.” should be sorted before those starting with “100.10.”. Hierarchical data cannot be indexed using simple INDEX ON … commands without wrecking the correct hierarchical sort order. One way to overcome this would be to do a SORT TO <NewTable> for the whole table immediately after a change happened. This is absolutely impracticable! Another approach could be to use a refreshable view. Alas, REQUERIES would become to slow, because the whole driving cursor has to be refreshed, even if only one record has been changed. What we need is something to generate an outcome like the following:

What is missing above is a second column that I named “Cbv” that holds the magic salt. BTW: the column/index name CBV stands for Compacted Binary View which describes the kind of data stored in that column. CBV-data can be indexed using a simple Visual FoxPro INDEX ON Cbv TAG ‘cbv’ command to solve all our hierarchical ordering problems!

Before I show you the final implementation, here are some things one has to think about when dealing with VFP’s limited DBF-capacities: A CHAR field is limited in size to 254 (maximum), the size of a compound key is limited even more: 240 bytes is the maximum per index key, if the collating sequence is set to MACHINE.

We could argue that it is easy to retain the correct sort order. We only have to use dimension values with leading zeros like so:

000000100.000000000.000000000.000000000.

000000100.000000001.000000000.000000000.

000000100.000000002.000000020.000000410.

000000100.000000002.000000010.000000000.

000000100.000000003.000000000.000000000.

Well, that is absolutely right! But, how many dimensions do we need to allocate and how many items should then be provided within each dimension? One upper boundary is our 240 bytes we cannot exceed due to FoxPro’s index limitation. Thus, if we reserve 9 bytes for each dimension plus the dimension delimiting dot, we would end up using 10 bytes per dimension. That means, that we have 24 dimensions with enough address space to reference 999,999,999,999 items within each dimension. Seen from a capacity view point only, the dimensions seem huge enough. But, using our regular decimal system in combination with leading zeros that have to fill up every place throughout all used records generates more difficulties than it solves.
Fist of all, there is a huge performance hit when dealing with larger record sets. Imagine we have over 100,000 TreeView records; then a new TreeView item has to be added to a dimension which then will become the one with the highest dimension width (a new deepest TreeView nesting level will be reached). All existing 100,000 TreeView records have to be touched to add a new dummy set of “000000000.” to their existing string.

000000100.000000000.000000000.000000000.000000001. << adding this one means:

000000100.000000001.000000000.000000000.000000000. << add dummies to all others!

000000100.000000002.000000020.000000410.000000000. << ditto.

000000100.000000002.000000010.000000000.000000000.<< ditto.

000000100.000000003.000000000.000000000.000000000.<< ditto.

Adding plus re-indexing renders this approach useless when running larger TreeViews. This technique is feasible only, if one is working with really small record sets, like in a Outlook scenario shown below:

Such kind of Outlook-style TreeViews are not used to display bulky data sets, but are employed for pure menu navigation purposes only! Thus, they are pretty much static, seen from the node count and ordering point of view.

The CBV Column

VFP brought us some cool functions and enhancements. Two of them are enhancements to the complementary CTOBIN() and BINTOC() functions. I do not want to re-type here what everyone can read in VFP’s help file about both function. Instead, I want to quote what is written in VFP’s help file in an additional chapter dealing with improved indexing support:

Create Small Indexes Using BINTOC( ) Sample

File: ...\Samples\Solution\Db\Index1.scx

This sample shows various indexing schemes you can use with numeric and integer data types to get significant savings in index size and disk space consumed. In addition, smaller sized indexes usually result in faster searches. The BINTOC() function makes it possible for you to convert an integer (numeric) value to a binary character representation.

Syntax

BINTOC(nExpression [, nSize])

Depending on the size of your expression, you can set the nSize parameter to accommodate the value of your expression in the least amount of characters.

The following line of code creates an index on a numeric field:

INDEX on line_no TAG line_no

The next time you are working with indexes on numeric integer data, consider using something like the following:

INDEX on BINTOC(line_no,1) TAG line_no

After playing with both functions for a while (BTW: there is a very informative demo under VFP’s Task Pane >> Solution Samples >> New in Visual FoxPro 9.0 >> BINTOC binary conversion) I started coding some routines to help me creating binary compacted string representations of the dimension values of my Vector column. The following listing takes a readable Vector expression like 454.42.753.146.8.1.77 and returns a CBV value that can be used for hierarchical indexing:

***---------------------------------------------------------------------------
*\\ Compact a "readable" VECTOR expression like 12.455.3.5566.1. into a
*\\ 	compressed binary vector string (with fixed dimension blocksizes!)
FUNCTION CompressVector(tcVector AS STRING, tnBlockSize AS Integer) AS STRING
	*\\ check input params
	IF NOT VARTYPE(m.tcValue) == "C" OR EMPTY(m.tcValue)
		RETURN "" && error condition
	ELSE
		*\\ Next line is necessary only if <tcVector>-data stems from a CHAR field 
		*** tcVector = ALLTRIM(m.tcVector)
		*//
	ENDIF
	*\\ let block size default to MAX_BLOCKSIZE
	IF NOT ( VARTYPE(m.tnBlockSize) == "N" AND INLIST(m.tnBlockSize, 4, 8) )
		tnBlockSize = MAX_BLOCKSIZE && MAX_BLOCKSIZE == 8 at the moment
	ENDIF
	*//
	LOCAL 	lnLoop AS INTEGER		,;	&& local loop variable
			lcNewVector AS STRING		&& local temprary string buffer			
	lcNewVector = ""
	*// define a symbol HSORT_SEPARATOR ”.”
	FOR lnLoop = 1 TO OCCURS(HSORT_SEPARATOR, m.tcVector)
		lcNewVector = m.lcNewVector + ;
			BINTOC(INT(VAL(GETWORDNUM(m.tcVector, m.lnLoop, HSORT_SEPARATOR))), "BRS")	
	NEXT
RETURN m.lcNewVector
ENDFUNC

The code I’m posting here is limited in that it allows only a fixed block size of 8 bytes at the moment. In other words, to save some extra bytes, I do not store dots between each dimension data any longer but use a fixed block size (of 8 bytes) instead. The final version will support 4 bytes and 2 bytes as well. The rule of thumb is: The less block size each dimension occupies, the more dimensions can be used to nest hierarchical (e.g. TreeView-) items. The following screenshot shows you the second Cbv column filled with: REPLACE ALL Cbv WITH CompressVector(Vector) and then INDEX ON Cbv TAG ‘Cbv’. Setting the order to Cbv afterwards results in the sorted browse like shown below:

There are some other interesting side effects:
For instance, it is possible to drop the Vector column completely before starting digital delivery of your application. Okay, it is pretty easy to spot what kind of encryption is running behind the scenes. Anyway, there is no human readable numbering any longer, which is a better protection than none at all :-)
With a second retrieval function (I called mine “DeCompressVector”) it is also possible to recreate the Vector column values from the Cbv column values. You will find all functions below (at the end of this post).
Because the binary vector expressions are unique (due to the uniqueness of object identity) they can also be used as primary keys!

End of Part I

This is the the end of my first part showing you how to setup a table to get sorted hierarchically on one column only! Keep in mind that there will be more supporting functions which will help us maintaining TreeView driving tables using a binary vector column like shown above. The most common scenarios that need to be supported are:

Inserting one or more items (creating table rows with appropriate Cbv values).

Deleting item(s).

Moving item(s).

Reorganizing driving table (re-indexing).

Re-creating (readable) Vector column entries, in case they were dropped.

In addition to that there will be even more functions to support specific TreeView behavior like expanding/collapsing branches and other things.

Happy coding

The X-Files

SET PROCEDURE TO (SYS(16)) ADDITIVE
RETURN

*\\ ***************** //* 
*** ***************** ***
*** HierachicSort.prg ***
*** ***************** ***
*// ***************** //*

#DEFINE HSORT_SEPARATOR "."
#DEFINE MAX_BLOCKSIZE 8

#IF .F. && ===================================================================
	MAX_BLOCKSIZE represents the maximum number of bytes it takes to
	compress one dimension value of a given VECTOR-Expression. At the moment
	(within Visual FoxPro) MAX_BLOCKSIZE MUST BE an 8 bytes Character expression 
	for CTOBIN() using "N.." as the 2nd parameter to work correctly. 
	The BlockSize setting is set for ALL Dimension. In other words: 
				One CANNOT mix 1, 2, 4 and 8 bit dimensions!

	The compact index (.cdx) we use for hierachial sorting has a maximum width 
	of 240 caracters. Thus, we can store vectors with up to 30 dimensions using
	an 8-bytes width (30 * 8 = 240) or 60 dimensions using a 4-bytes width
	accordingly. The highest scalar dimension value that can be compresses into 
	8 bytes is (15 places) which is 999,999,999,999,999 => 999 trillions!

	BTW: 
		9,007,199,254,740,992 is VFP's mamimum digits of precision in NUMERIC 
		computations (16 digits).

	In other words: At the moment we are able to handle VECTOR-Expression up to 
	30 dimensions with each dimension holding up to 999999999999999 possible 
	sub-dimensions or nodes!

#ENDIF && ===================================================================

***---------------------------------------------------------------------------
*\\ Compress a given string/numeric value
*\\ Parameter checking and function overloading
FUNCTION Compress(teValue AS VARIANT) AS STRING
	*\\ the largest <teValue> integer value is 999999999999999
	IF VARTYPE(m.teValue) == "N"
		IF m.teValue > 999999999999999
			*\\ error condition
			RETURN ""
		ELSE
			*\\ call implementation
			RETURN CompressNumber(m.teValue)		
		ENDIF
	ELSE
		IF VARTYPE(m.teValue) == "C" AND NOT EMPTY(m.teValue)
			*\\ the largest <teValue> string value is >999999999999999<
			IF m.teValue > "999999999999999"
				*\\ error condition
				RETURN ""
			ELSE
				*\\ call implementation
				RETURN CompressString(ALLTRIM(m.teValue))
			ENDIF
		ELSE
			*\\ error condition
			RETURN ""
		ENDIF
	ENDIF
ENDFUNC

***---------------------------------------------------------------------------
*\\ Compress a given string (compress() function overload#1)
FUNCTION CompressString(tcValue AS STRING) AS STRING
	*\\ Do the job w/o parameter testing
	RETURN BINTOC(INT(VAL(m.tcValue)), "BRS")
	*//
ENDFUNC

***---------------------------------------------------------------------------
*\\ Compress a given number (compress() function overload#2)
FUNCTION CompressNumber(tnValue AS NUMBER) AS STRING
	*\\ Do the job w/o parameter testing
	RETURN BINTOC(m.tnValue, "BRS")
	*//
ENDFUNC

***---------------------------------------------------------------------------
*\\ Decompress a given (compacted) binary string value
FUNCTION DeCompress(tcValue AS STRING, tnBlockSize AS Integer) AS STRING
	*\\ check input params
	IF NOT VARTYPE(m.tcValue) == "C" OR EMPTY(m.tcValue)
		RETURN "" && error condition
	ENDIF
	*\\ let block size default to MAX_BLOCKSIZE
	IF NOT ( VARTYPE(m.tnBlockSize) == "N" AND INLIST(m.tnBlockSize, 4, 8) )
		tnBlockSize = MAX_BLOCKSIZE && MAX_BLOCKSIZE always == 8 in VFP
	ENDIF
	*//
	IF LEN(m.tcValue) = m.tnBlockSize
		RETURN DeCompressValue(m.tcValue)
	ELSE
		IF LEN(m.tcValue) <= m.tnBlockSize
			RETURN DeCompressValue(PADR(m.tcValue, m.tnBlockSize, CHR(0)))
		ELSE
			RETURN DeCompressValue(LEFT(m.tcValue, m.tnBlockSize))
		ENDIF
	ENDIF
	*//
ENDFUNC

***---------------------------------------------------------------------------
*\\ Decompress() standard implementation
FUNCTION DeCompressValue(tcValue AS STRING) AS STRING
	*\\ parameter checking is done in ExpandValue()
	RETURN TRANSFORM(INT(CTOBIN(m.tcValue, "NRS")))
	*//
ENDFUNC

***---------------------------------------------------------------------------
*\\ Compact a "readable" VECTOR expression like 12.455.3.5566.1. into a
*\\ 	compressed binary vector string (with fixed dimension blocksizes!)
FUNCTION CompressVector(tcVector AS STRING, tnBlockSize AS Integer) AS STRING
	*\\ check input params
	IF NOT VARTYPE(m.tcValue) == "C" OR EMPTY(m.tcValue)
		RETURN "" && error condition
	ELSE
		*\\ Next line is necessary only if <tcVector>-data stems from a CHAR field 
		*** tcVector = ALLTRIM(m.tcVector)
		*//
	ENDIF
	*\\ let block size default to MAX_BLOCKSIZE
	IF NOT ( VARTYPE(m.tnBlockSize) == "N" AND INLIST(m.tnBlockSize, 4, 8) )
		tnBlockSize = MAX_BLOCKSIZE && MAX_BLOCKSIZE always == 8 in VFP
	ENDIF
	*//
	LOCAL 	lnLoop AS INTEGER		,;	&& local loop variable
			lcNewVector AS STRING		&& local temprary string buffer			
	lcNewVector = ""
	*//
	FOR lnLoop = 1 TO OCCURS(HSORT_SEPARATOR, m.tcVector)
		lcNewVector = m.lcNewVector + ;
			BINTOC(INT(VAL(GETWORDNUM(m.tcVector, m.lnLoop, HSORT_SEPARATOR))), "BRS")	
	NEXT
RETURN m.lcNewVector && + "."
ENDFUNC

***---------------------------------------------------------------------------
*\\ Expand a compressed (binary) VECTOR string into a "readable" VECTOR
*\\ 	expression like 12.455.3.5566.1.
FUNCTION DeCompressVector(tcExpression AS STRING, tnBlockSize AS Integer) AS STRING
	*\\ check input params
	IF NOT VARTYPE(m.tcExpression) == "C" OR EMPTY(m.tcExpression)
		RETURN "" && error condition
	ENDIF
	*\\ default block size to max block size
	IF NOT ( VARTYPE(m.tnBlockSize) == "N" AND INLIST(m.tnBlockSize, 4, 8) )
		tnBlockSize = MAX_BLOCKSIZE && MAX_BLOCKSIZE is always 8 in VFP
	ENDIF
	*//
	LOCAL 	lnLoop AS INTEGER		,;	&& local loop variable
			lcNewVector AS STRING		&& local temprary string buffer
	lcNewVector = ""
	*//
	FOR lnLoop = 0 TO ( LEN(tcExpression) / m.tnBlockSize ) - 1		
		m.lcValue =	SUBSTR(m.tcExpression, m.lnLoop * m.tnBlockSize + 1, m.tnBlockSize)
		lcNewVector = m.lcNewVector + ;
				TRANSFORM(INT(CTOBIN( 						;
				SUBSTR(m.tcExpression, m.lnLoop * m.tnBlockSize + 1, m.tnBlockSize),;
				"NRS"))) + "."
	NEXT
RETURN m.lcNewVector
ENDFUNC

2011-04-30T16:50:00.000+02:00

Latest News

This section of my VFP Blog gets filled at random times and with random content. One could say, this is the remaining most blog-like part of my VFP Blog. Most of the entries will be dealing with what I’ve added to the other sections of my blog lately. Thus, it seems to be a good idea to check this news section first…

Wednesday, August 30, 2011, 06:05:00

As time goes by…
I finished my C# course and passed the examine. Now, instead of starting using it, I’m facing a new challenge:
I need to set up some Apache-based internet sites (with cool interactivity)! Thus, I started learning (renewing) PHP and ALAX. I’m afraid, learning will never end :-)

I’m still working on my VFP TreeView (but not spending too much time on it at the moment). At least I will make a download link available.
I’m going to add more chapters to my FoxTools reference in the future as well as to my OOP-basics chapters, and: I have written an new exhaustive post about cool and unknown(!) EVENTBINDING features!

Finally, I’m afraid, I have to stop posting long “articles” here on this blog because of missing free time. Creating new VFP blog entries using my current blogger template is too time-consuming. I will reset this VFP blog to one of the common/regular layouts, so I can publish my future VFP-related latest news here in minutes, not in hours.

I won’t drop my VFP-related activities completely – never ever! But there will be another platform for my activities (watch out on www.alligora.com).

Monday, July 18, 2011, 13:00:00

Some of you found all my download links broken last days. This was caused by a high jacking attack on my CMSystem I was running on my FoxQuill.de website. I missed an important maintenance upgrade and found my CMS site cracked short time later. So, take my advice and never miss any CMS upgrades! I deleted my CMS test-drive installation (containing my blogger-resources as well). Thus, sorry for going offline for some days, now you should be able to download again.

Monday, May 02, 2011, 24:00:00

Another step towards the final release of my native TreeView: I added the first part of hierarchical indexing
Let me introduce to you *Bruno* – my RR

Friday, April 29, 2011, 22:25:00

Finally I found some time to start filling some old gaps; I added a first entry under the VFPX projects section
Next, I restructured my FoxQuill framework section because I am going to post new entries there ASAP.
Last but not least, my native TreeView story develops further. There are only two or three post left to describe some needed background.

Monday, April 25, 2011, 23:45:00

As announced: I added a new entry under my “Tips & Tricks” section >>> LOADPICTURE() Function – Some Myths Revealed.
Started publishing some thoughts under my framework section “FoxQuill”, too.

Tuesday, April 12, 2011, 15:15:00

Added a new “How to…” under my Miscellaneous section.
Busily working on my final native VFP TreeView. See chapter 5 under my Complex Controls section.
Just going to release another very interesting entry under my Tips&Tricks section. Be prepared :-)

Monday, April 4, 2011, 23:35:00

Gosh, I started a C# learning course end of last year – 6 month intensive fulltime-training: 8 hours a day! Folks I can tell: many new classes and new concepts to learn but after a while one gets used to it. Especially the VS2010 IDE is cool! VFP’s code editor and class/form designers look a little bit shabby after some month working exclusively with VS2010. The only feature I still was missing in VS is VFP’s command window. But then I found a little something called FastSharpForm written by Matthew Manela (see below)

So, now I can hack in a simple line containing a C# expression or even a whole code block and click [run] – an Voilà! there it is, the result (or an error :-) Just like using VFP’s command window – well, almost. To be honest, still, there are missing a lot of well-known VFP features. But who knows, maybe Matthew will add some of them to his smart little helper in the future!

Tuesday, February 15, 2011, 23:22:00

Just “recovering” from the second removal within one year (the third within the last two years) - From now on the old saying: “Three removals are as bad as fire” makes much more sense!
After more than three month without any stable internet connection, it was good to see my VFP blog today filled with many comments waiting to be accepted/published. I am happy to see that there are many people still out there willing to read my writings.
At first glance, Visual FoxPro is getting closer to the binary nirvana year after year? (;-) Hold on! There is life in the old dog yet, and I am going to prove that pretty soon! Thus, stay tuned and be prepared…

Wednesday, September 15, 2010, 09:25:00 Finally published an old demo (a VFP exe) you may want to play with while waiting for “the real thing” – the One and Only Native VFP TreeView :-) http://myvfpblog.blogspot.com/2008/02/native-treeview-part-iv-b.html Thursday, August 26, 2010, 16:25:00 Since my last posting some months went by neither giving me time to write any blog updates nor adding new stuff as expected. Please, don’t blame me for that! Even if I would like to post much more, reality is that driving this blog is only my hobby and not my profession. Beside my VFP work I began learning C# (using VS2010) which is another good exculpation for not fostering these pages during the past months.

There are some unfinished “projects” I started here that I definitely will bring to a presentable/usable state!

1.) The “ominous” native VFP tree view. This still is a “living” work in progress! It was (and still is!) attracting interest! What’s going on “behind the green door” is that I’m busily working on some essential speed improvements, which tend to be much more than simple refactorings!

2.) The Global Resource Manager. This also is a work in progress! In fact, I’m actually working on that solution (parallel to writing these lines)!

3.) The Complete Foxtools Reference. Again, this isn’t forgotten, but does not have that high priority ATM.

4.) The RTF2HTML Converter. I dropped that project because there are enough free plug-ins available that do that job very well.

5.) VFP’S BASICS. My initial intension when starting this thread was to have a place where I can pile up my own OOP-related findings and believing so that I’m able to look them up whenever I needed to do so. Still, part II & III have to be written, even part I needs to be polished up, but like my Foxtools reference, this isn’t flagged “urgent” ATM.

Bruno - My RR (Rhodesian Ridgeback)

2011-04-30T15:42:00.000+02:00

Version: 1.00.01 - last update: Saturday, April 30, 2011, 16:50:00

Everybody should have one

Let me introduce to you, BRUNO, my four years old RR boy

2011-04-29T22:10:00.000+02:00

VFPX Projects

This section holds topics dealing with VFPX projects – existing and maybe some future ones…

There are very cool tools, addons and other smart gizmos written in VFP (or even using C/C++) to enhance Visual FoxPro available for free download on VFPX. The VFP community is still alive and agile! Some of the cool tools are designed to speed up development, others can be built into one’s own applications to add some sophisticated functionality at runtime. What’s still missing is some kind of an overall picture – a path to follow while designing and implementing all kind of VFPX addons, either design-time, or run-time related ones! I’m not the guru who can tell the one and only truth about such a “mission to mars”; I don’t even come close! In addition, I must admit that some years passed by since I tried to use some VFPX addons in my own applications the last time. What I do have instead is, enough experience what’s best not to do with VFP

This section will be the place to read about VFPX projects I was working with and, sometimes, contributed to. As usual I start without a precisely predefined layout. I hope, some fine day a golden thread will appear of its own volition ;-)

Table of Contents

VFPX – A Community-Based Effort

Still to be (re-)written / published.

VFPX – VFP 9 SP2 Help File

The Visual FoxPro 9 SP2 Help file corrected, supported, and enhanced.

VFPX - Help file corrected, supported, and enhanced

2011-04-29T22:07:00.000+02:00

Version: 0.01.10 - last update: Saturday, April 30, 2011, 01:30:00

Get a refurbished and enhanced Visual FoxPro Help file.

I downloaded a copy of the latest VFP9 SP2 help file (dv_foxhelp_vfp9sp2_b6.exe) today.

I contributed the LOADPICTURE() help page.

At the end of this help page my example #4 is now missing.
It had to be dropped because otherwise the whole page would have been to long.

No problem, you can get the whole story (and even more) directly from here.

Do not forget to get your own copy of the latest VFP Help file!

Francis Faure who is the project manager is doing a really great job!
It is hard to keep track of all the little and large oddities that need
to be corrected – a time-consuming and sometimes nerving task!

Thanks Francis!

The Future of FoxQuill

2011-04-29T17:20:00.000+02:00

Version: 1.11.01 - last update: Saturday, April 30, 2011, 02:10:00

FoxQuill will become FoxQuill.NET

VFP’s Future

Visual FoxPro will not die abruptly – neither tomorrow, nor next week! There is enough work left to be done for smart and experienced VFP developers – okay, maybe with additional programming language skills. I am sure, migrating VFP/XBase based legacy-systems to C# or any other language will become a pretty remarkable line of business in the future.

The Future of FoxQuill

Microsoft’s initial release of the NET framework was on 13. February 2002. During the past decade countless books were written touching almost every NET-related aspect. Why should one think about doing another one? Well, first of all, I think this is a universal question, which also is true for other businesses: “Why should we build another new type of car? Don’t we have enough to choose from?” I believe, one possible answer is: “As long as we can make something better, we should go for it!” Another good answer: “As long as we can re-sharpen something to become more precise, we should do that, too!”

But there is more to mediate on! Lately, I read Jeff Jarvis’ book What would Google Do? I do recommend reading it! Amongst many other things, I learned that the Internet brought a big change in the global market: Yesterday we had some (few) big companies; earning big bucks was only possible for these mainstream players. Today, with the help of the internet, there are much more small-sized companies. Specialization is the buss word today! Do not try to capture all potential customers in your country, but only a small group that you’ve tailored your perfect fitting offer for. With the help of the internet, your customer base will be multiplied for sure. Now, the whole world has become your country!
My strategy is to niche a market with FoxQuill.Net in a special way. The experience I’ve made learning C# on the .NET platform, I will publish as an open-source book. In addition, I will publish parts of FoxQuill also as an open-source project. I just started to add and refactor some of my old FoxQuill classes. My intention is to make them “look and feel” more like their counterparts in my C#-based FoxQuill.Net version. An effort that will pay back when finally migrating to the .Net platform one fine day. Finally, FoxQuill.Net will be an open-source project as well! I would never presume to create a 100% compatible VFP.NET clone (see below). When Microsoft buried VB6 and published VB.NET they must have had good reasons not to recreate a 100% backwards compatible VB.Net version!

Good Starting Points

Most VFP developers seriously interested in the .NET platform know about the Visual FoxPro Toolkit for .NET. I believe, a closer look at it gives you a good starting point. But, it is not my intention to trample down that trail again. I believe, that most of the authors of .NET books first learned C#, or VB.NET thoroughly and gained experience while working with Visual Studio. They all started writing after they have been there, done it, got the T-shirts :-) I will start now, immediately writing about what I am learning. Even better, writing about what I am missing and what is hard to understand, because there is counterpart within VFP. The best way to learn C#/VB.NET seen from my VFP-biased point of view surely differs from the mainstream. Voilà: there the niche is :-)

VFP.NET the Unborn ‘Flatliner’

Lately I followed a thread on Google groups VFP.Net Compiler Community Support Group. In a nutshell: There is (or was?) a company named eTecnologia. They sell (or sold?) a Net Extender for VFP. This tool was intended to be a VFP wrapper that lets us access all the cool .NET functionality flawlessly. But the wrapper was very instable and thus, almost good for nothing! Next they told us, that pretty soon they would come up with a VFP Developer Studio – a complete VFP 9 port to the .NET platform! Still it is not much more than an alpha version, even today (April 2011).
IMOH: Today, no small (even no mid-sized) company is able to allow itself the luxury of doing a full-featured (100% compatible) VFP 9 to VFP.NET port! Maybe they might be able to implement 95% of VFP’s overall functionality in the first half of their “migration-game”. But, for the remaining 5% of VFP’s functionality ( – believe me –) they will need much more than a second half!

FoxQuill.Net Another Unborn Successor

The future of Visual FoxPro, better the spirit of VFP, must no longer be controlled by bigger brothers. Today, it is possible to form developer teams loosely coupled worldwide from small herds to large swarms :-) Today, we are able to create a new VFP.NET implementation by our joint efforts from scratch. The outcome may not be the real thing compared to VFP 9, but it will definitely be an enhanced development environment that re-enables us to write bullet-proof, stable running, paramount apps for modern operation systems in the shortest possible time! We must not waist our money on compatibility issues! Let’s learn from the past, but do not lose time to repeat it unsuccessfully! Of course, backward compatibility is a “nice to have”-feature, especially if one owes a lot of old sources written in VFP, or even in FPW (or even better in FoxPro for DOS/MAC/UNIX :-)
Most cardinal errors made in the past stem from how program logic was implemented! The logic (the coded behavior) of a program was bound to the programming language much too tight. Every time you have to rewrite parts (or all) of your code during migration, you encounter this flaw. Look at good old macro substitution for example which is a very VFP/XBase - specific feature. Doing an automated port of a PRG that is heavily using macro substitution to C# is next to impossible!

Revert Backward Compatibility to Forward Compatibility!

Let us face some of the troubles a Tomorrow VFP Developer may ran into:

Microsoft stopped supporting and maintaining VFP.
VFP will no longer be compatible with Win 8, 9 or 10.
No raising generation of VFP developers any more.
Tons of NET programmers with neither XBase knowledge, nor any sympathy.
Many companies wish to upsize/migrate their legacy VFP systems to .NET (but only for little fees, please!)
Missing migration tools will hinder you, because you are to expensive!

The business landscape described above is closer than one might think! A .NET developer always advises any CEO during an in-depth consultation to migrate to the .NET language that meet his skills! No .NET developer would phone you up and ask for you assistance because of your prominent VFP skills – never ever! At the utmost, they may need your expertise during migration of their VFP tables. Upsizing dbf content to any kind of SQL Server instance might spawn subtle errors, as we know! The rest of the plot is very simple: all legacy VFP source code gets dropped. A complete rewrite will be done, because with some very clever NET tools this can be realized very fast and very cheap by someone with less .NET-skills than yours!
Now, how could we revert compatibility to always point forward to our latest, most powerful implementations? The answer is astonishingly simple: We have to GENERATE all of our source code by using a program and not by hacking in each line manually! Code that was generated by a machine can be maintained by a machine as well. Automatic maintenance finally leads to computer-based upgrading, upsizing and, if necessary, migration. All we have to do is decouple user interface design and program logic definition from the process of creating the corresponding source code. Look at Microsoft’s WPF and you know what I mean when I’m taking about decoupling the user interface design. This technology is already there! Decoupling program logic (the entire application behavior) from generating the corresponding source code can be realized in almost the same way. Believe me!
Using my (future:-) FoxQuill.Net development system, resembles the way we create internet pages in an WYSIWYG editor, today. Yes, it still will be possible to manually write and add source code, but that’s generally not necessary in 95% of all business cases. Even my so called ‘micro-workflows’ can easily be assembled by selecting the appropriate building blocks from context sensitive lists. Dropping them on a design form afterwards and finally arrange/configure them is all that has to be done. I like to point you to Google’s App Inventor for Android where you can watch some short YouTube demos and tutorials. Especially the blocks editor user interface looks very promising (see below)!

Google still is some development-miles away from having the perfect App generator, but we all know that they will have one in the near future :-)
GUI layout, workflows, messaging, data-storage, -manipulation and -transport, as well as event-handling and system configuration; all these things are aspects that can be configured using universal XML-based schemas. Any FoxQuill.NET editor (just like Google’s Block-Editor shown above partially) emits XML-based data which belongs to the additional abstraction/separation layer I mentioned earlier in this post. Thus, what we are creating during our future development with FoxQuill.NET is neither .NET’s IL code, nor C#/VB.NET source code, but XML files representing a concrete DESIGN; e.g. some GUI layout, or a process workflow, maybe an inter-object messaging specification, or some storage structure definition, or a details system configuration definition, to name only a few possibilities.

Pros & Cons

At the beginning, as long as adequate tools are rare, there is less interactivity compared to VFP. VFP’s command window is a very unique and useful feature, for example. Such pervasive interactivity normally requires an interpretative language driving the system like Python. Luckily, there are much more Pros than Cons!
Every XML output generated by a designer can be preprocessed and/or redirected before the target generator starts it’s code generation. This enables dynamic workflows: we will be able to enhance/add, modify or delete parts of the XML data on the fly based on external conditions. Another big plus is, that the designer tools themselves will be able to pre-check the user-input. With these client-site validations enabled (available only in a local workstation mode) it is possible to catch potential errors at a very early state (still in the designer), which helps to eliminate unnecessary development round-trips.
The XML files generated by the different designers can be interchanged over the internet. The generation site can be a remote one. Thus, someone may build some very specialized generator, or a much better version than the original one provided by FoxQuill.NET. The developer of such a super-generator tool then may publish the availability of her advanced functionality so that the community knows about it. After that, she can offer access to the (remote) service for free, or associated with a certain pricing plan. Because a generation service outputs text files only (e.g. C# source code), such a distributed remote source code generation is secure and can be packed and encrypted in addition.

<to be continued…>

The LOADPICTURE() Function – (Some) ALL Myths Revealed!

2011-04-25T19:21:00.000+02:00

Version: 0.02.02 - last update: Thursday, April 26, 2011, 14:35:00

All you have to know about VFP’s LOADPICTURE() function

Intro

VFP’s LOADPICTURE() creates a COM picture object and returns a fancy ‘crippled’ interface reference! VFP’s LOADPICTURE() function is nothing more than a wrapper around the Windows API function called OleCreatePictureIndirect(), which in turn creates a COM picture object. These COM–wrapped objects are used by many ActiveX controls. You can find out more about OleCreatePictureIndirect() here. There are some VERY GOOD reasons to use VFP’s LOADPICTURE() functionality! After all, carelessly using COM image objects created by VFP’s LOADPICTURE() function in conjunction with VFP’s native Image controls will introduce some almost non-trappable very tricky malfunctions! If you want to get the best out of it, without spending hours on debugging what seems to be impossible, read the rest of this post!

This is the syntax of the API call wrapped by VFP’s LOADPICTURE() function:

OleCreatePictureIndirect(pPictDesc,; && Pointer to the structure of parameters for picture
			   Riid	  ,;&& Reference to the identifier of the interface
			   fOwn	  ,;&& Whether the picture is to be destroyed
			   ppvObj     && Address of output variable that receives the 
				        && Interface pointer requested in riid

As we all know, the right way to call a COM object’s implementation (inside a DLL) is using one of its interfaces. To figure out the interfaces that are available within a picture COM object, use VFP’s Object Browser. You can load either the “StdTypes” DLL itself (at <windir>\SYSTEM32\OLEPRO32.DLL), or its type library file (<windir>\SYSTEM32\STDOLE2.TLB).

COM Interfaces

As you can see, in VFP’s Object Browser the interface called “PICTURE” is VFP’s default interface that is returned each time we are using some command like:

oPicture = LOADPICTURE(GETPIC())

The oPicture reference above is a COM object reference of an interface named “Picture” through which we can access our image’s properties and methods.

Let VFP’s IntelliSense help us and type opicture. into the command window after we created a picture instance like shown above. IntelliSense shows us a list of five properties and one method accessible through this primary interface. BTW: The same popup can be shown within your debugger:

This Picture interface is suitable in cases where we only want to pass a COM object reference to another ActiveX control, or we want to display the image using VFP’s own native image class like this:

_Screen.AddObject("oImage","IMAGE")
oPicture = LOADPICTURE(GETPIC())
_SCREEN.oImage.PictureVal = m.oPicture
_SCREEN.oImage.Visible = .T.

However, if we try to use the COM object’s render() method directly, bypassing the use of VFP’s Image object, we will only receive an OLE error complaining about non-optional parameters.

Without any further investigations, we are stuck at this point!

By The Way 1,2,3

There is a BUG in the VFP online documentation for the image object’s PictureVal property! Actual writing reads: “If eExpression is an object, the object must be in an IPicture interface format. The IPicture interface format is the same format returned by the LOADPICTURE( ) Function.” This is wrong! It should be “If eExpression is an object, the object must implement one of the following interfaces: “Picture” OR “iPicture”, which both _*do*_ work! The Picture interface is the same returned by VFP’s LOADPICTURE() function. If you need the iPicture-interface, you can retrieve it by the help of VFP’s GETINTERFACE() function.”
VFP’s SAVEPICTURE() function is nothing more than a wrapper around the SaveAsFile() function of the COM picture object (accessible by VFP through the iPicture interface)!
You can read one sentence in VFP’s online help about the LOADPICTURE() function: „If cFileName is omitted, the null picture is returned“. This sounds Greek. However, as you can read here, it is nothing more than a parameterization option defined in the OleCreatePictureIndirect() function of the underlying Windows API. The NULL-Picture-Object is nothing else, but an uninitialized object which can initialize itself through the Load() method of its IPersistStream interface. Got it? No? Do not hesitate – nothing we have to deal with (in the next future:-)

To make a long story short

… Let me show you how to get the darn thing work. As you should have guessed, we must not use the Picture interface that we get back using the LOADPICTURE() function, but the other (hidden) interface: IPicture is the right one to use! And this is how to get the right COM-Object reference:

oPicture = LOADPICTURE(GETPIC())
oIPicture = GETINTERFACE(oPicture, “iPicture”)

Typing in the first line in VFP’s command window, you will get some similar GETPIC() dialogue like below:

I have a little image on my disk called “tree.jpg” – a 100 x 100 pixels JPEG file that I will use during this walkthrough. Now, if we are using VFP’s Intellisense on oIPicture it shows us a longer list of properties and methods (see Object Browser screen shot below). The biggest point is that we now can use our COM object’s render() method directly!

The COM Object’s Render() Method

This is how the render() method’s signature reads in VFP’s Object Browser followed by a short description of each parameter:

Render(hdc As Integer, x As Long, y As Long, cx As Long, cy As Long, xSrc As Long, ySrc As Long, cxSrc As Long, cySrc As Long, lprcWBounds As Void) As H Result

[target] hdc := the device context handle (a pointer to something like a canvas)
There are two Windows API functions to retrieve a handle to an existing device context: GetDC() and GetWindowDC().

[target] x:= left-property of output-rectangle (top left corner’s X-coordinate)

[target] y:= top-property of output-rectangle (top left corner’s Y-coordinate)

[target] cx:= width-property of output-rectangle (the width of output)

[target] cy:= height-property of output-rectangle (the height of output)

Up to this point all coordinates are measured in pixel (we VFP developers are used to use) and could be mapped
to LEFT, TOP, WIDTH and HEIGHT properties of an imaginary VFP image object.

[source] xSrc:= X-offset into image source (from where column-copy starts)

[source] ySrc:= Y-offset into image source (from where line-copy starts)

[source] cxSrc:= Width of each line to copy (#no of columns)

[source] cySrc:= Height of each column to copy (#no of lines)

HiMetric

To make things a little bit more “interesting” one have decided to use HiMetric units for some of the COM object’s properties (those dealing with the image source dimensions). That is why a 100x100 pixels image loaded from disk ends up in our internal COM in-memory representation having 2646 x 2646 units!

Coordinates

“HiMetric” scaling must have been not difficult enough for some of them, someone decided to move the coordinate-origin (0, 0-point) from the top-left corner of the COM-Image source to the lower-left corner (maybe to spice things up ;-)

Some manual testing

Let’s have a look at my original source image:

Let us now assume, that we already have a valid handle to a device context to render our image on. The following call to render()

WITH oIPic
   = .Render(m.hDC, 0, 0, 100, 100, 0, 0, .Width, .Height, NULL)
ENDWITH

would then produce the following output:

The origin of the COM coordinate system is somehow rotated in memory by 180° After some wild guesses one may find out that the following code produces the expected output:

WITH oIPic
   = .Render(m.hDC ,;
             0,    0   ,   100 ,   100     ,;
             0, .Height, .Width, .Height*-1,;
             NULL)
ENDWITH

We have to understand what’s going on internally to see things a little bit clearer! The image loaded into memory is nothing more than a memory block filled with pixel related color values. This memory block can be abstractly treated as a rectangle. During rendering, which internally is the process of transferring data from the source rectangle to the destination rectangle, our COM object uses different values which are passed in through parameter #6 to #9 (the [source] parameters) to control the process:

The origin of the source rectangle, one could name “copy starting point”.
The width and the height of the source rectangle to support cases when we do not want to render out a source image completely!
The direction in which to “read-out” the source data (bytes).

It is important to know, that the very first source pixel (the one that is the origin of the source rectangle) always gets rendered out at position 1,1 of the target rectangle. The second source pixel (what exact pixel will be copied next depends on the read-out direction) gets renders out at position 2,1 and so on. Thus, by selecting the appropriate origin to start from, it is possible to render a mirrored image into the destination device context.

The xSrc und ySrc Parameter

The 6th and 7th parameter value of the render() function determine where the starting point of the copy process within the image source lays. One of the 4 corners of the source rectangle will become the origin. Below, we can see the memory based COM – image with a given source rectangle (the red frame). In this case the source rectangle’s size matches the whole image. The coordinate pairs of all four valid xSrc/ySrc – combinations are also depicted. The values shown reflect HiMetric scaling (a 100x100 pixels square on a 96 dpi device context)

Through determining the origin of where to start reading out the source pixel values, we also determine the direction of read out indirectly! The direction of read out is established by the sign of the last two input parameters (cxSrc and cySrc) of the render() method. (Don’t be surprised, just take it as read :-)

The cxSrc und cySrc Parameter

On the one hand, the 8th und 9th parameter determine width and height of the source rectangle, on the other hand they also determine the read direction during the rendering data transfer. The absolute values ABS(cxSrc) and ABS(cySrc) define the width and height of the source rectangle, the sign of both values (+/-) the direction of read out. The picture below might help to shed some light on that:

The [source] coordinate parameters of the oIPic.Render() call (see above) tell us: “Position the ‘copy from – origin’ at x = 0, y=2646 (see 2nd pic from the left within the image just above) and start the line-wise transfer from there. Each transferred line in –> x direction with a pixel-width defined by ABS(HiMetric-Units) of the cxSrc parameter. Proceed with next line in -y direction. Loop until as much pixel lines were transferred as defined in ABS(HiMetric-Units) of the cySrc parameter. Now, we are able to mirror any image during rendering along both axis:

Solving the Hourglass Problem

There is another weird VFP behavior most of us already encountered in the past: the “hourglass problem”! Sometimes, we want VFP to refresh some form content which results in a cascading refresh. Controls that have to be refreshed sometimes have images assigned to their .Picture properties. Such image references always point to a file on the disk (or the app/exe which makes no difference). In other words, VFP has to access the disk in one way or another. If these disk accesses last more than a few milliseconds, then the operating system changes the mouse cursor to an hourglass! And sometimes VFP isn’t aware of that change. As long as the user doesn’t touch the mouse, VFP doesn’t refresh (reset) the mouse cursor symbol. Thus, for the user it seems like VFP still is busy. With the help of VFP’s LOADPICTURE() function (and the newly introduced .PictureVal property) it is now possible to avoid a wrong hourglass cursor display. Using code like the following one

_Screen.AddObject("oImage","IMAGE") 
oPicture = LOADPICTURE(GETPIC()) 
_SCREEN.oImage.PictureVal = m.oPicture 
_SCREEN.oImage.Visible = .T.

never ever again will display the wrong hourglass mouse cursor, because there no longer is any disk access! Before you now shout: “That’s COOL!”, read on; there is a severe drawback caused by a VFP bug!

Solving the PictureVal Bug

This is a short excerpt taken from one of my elder VFP projects. First, the INIT() of one of my VFP Image classes is the place where I load the COM-Images

LOCAL lcPicture AS String
WITH THIS
   IF .EnableMultiStatePictures
	*\\ reassure we have pictures to display 
	lcPicture = JUSTFNAME(.Picture)
	IF EMPTY(.PictureEnabled)
		.PictureEnabled = m.lcPicture
	ENDIF
	IF EMPTY(.PictureDisabled)
		.PictureDisabled = m.lcPicture
	ENDIF
	IF EMPTY(.PictureMouseOver)
		.PictureMouseOver = m.lcPicture
	ENDIF
	IF EMPTY(.PicturePressed)
		.PicturePressed = .PictureMouseOver
	ENDIF
	IF EMPTY(.PictureSelected)
		.PictureSelected = .PicturePressed
	ENDIF
	*\\ set basic state
	.ImageState = IIF(.Enabled, 1, 0)
	*//
   ENDIF
   IF .EnableComPictureHandling
	*\\ The reason for using COM instances of JPG-images in conjunction with Image.PictureVal properties
	*\\	is, that we no longer have disk access. Thus, the hourglas mouse cursor never appears when
	*\\	clicking or hovering in/out on an image (refreshing it). BUT we have to be very carefully NOT
	*\\	to assign the same COM interface to THIS.PictureVal _twice_in_a_row!!! Doing so, will result in
	*\\	VFP looses the COM-reference to that picture object randomly. For more details see
	*\\	THIS._old_oPictureDisabled_Access() method.
	.PictureEnabled = LOADPICTURE(LOCFILE(JUSTSTEM(.PictureEnabled),JUSTEXT(.PictureEnabled),"Locate image"))
	.PictureDisabled = LOADPICTURE(LOCFILE(JUSTSTEM(.PictureDisabled),JUSTEXT(.PictureDisabled),"Locate image"))
	.PictureMouseOver = LOADPICTURE(LOCFILE(JUSTSTEM(.PictureMouseOver),JUSTEXT(.PictureMouseOver),"Locate image"))
	.PicturePressed = LOADPICTURE(LOCFILE(JUSTSTEM(.PicturePressed),JUSTEXT(.PicturePressed),"Locate image"))
	.PictureSelected = LOADPICTURE(LOCFILE(JUSTSTEM(.PictureSelected),JUSTEXT(.PictureSelected),"Locate image"))
   ENDIF
ENDWITH

This is the content of the _old_oPictureDisabled_Access() method:

*\\ It took me hours to find out what was going wrong! *\\ These are my findings: *\\ Assigning an interface reference of a COM-ImageObject *\\ (created using VFP's LOADPICTURE() function) to *\\ This.PictureVal property will work properly as long as *\\ you do not *reassign* the same reference to .PictureVal again!! *\\ Reassignment may work many times flawlessly, but (and that's for sure!) *\\ eventually VFP looses its internal COM reference completely *\\ after a reassignment! Apart from the fact that reassignments *\\ aren't necessary at all (coz the picture already is shown), *\\ they might occur, especially if one had coded COM-image reference *\\ assignments to .PictureVal properties all over the place generously *\\ without knowing about this issue! *//
*\\ My solution now is to use a new integer property <.ImageState> *\\ that may hold one of the following values: 0=Disabled; 1=Enabled; *\\ 2=MouseOver; 4=Pressed; 8=Selected (a bit field). This property tells *\\ me exactly which COM-ImageObject reference is assigned to *\\ the .PictureVal property at any moment. In all places where I *\\ have to assign another COM-Image reference, I carefully test *\\ against the <.ImageState> property value before assigning the *\\ new reference to eliminate reassignments completely!

The bottom line is: THIS IS A VFP BUG!
But, luckily, a solution (a workaround) is pretty easy to implement. In fact, it may even help to speed up your executable/application. I have to stress it here once more: The buggy behavior does only appear if one is reassigning the same COM interface reference to an image-object’s PictureVal property more than once in a row!

The the first loop of following code works flawlessly:

LOCAL lnLoop AS Integer, oComPic1 AS olePic
oComPic1 = LOADPICTURE(GETFILE())
oComPic2 = LOADPICTURE(GETFILE())
TRY
	_Screen.Addobject("oImage","IMAGE")
CATCH
FINALLY
	_Screen.oImage.Visible = .T.
ENDTRY
FOR lnLoop = 1 to 100
	_Screen.oImage.PictureVal = m.oComPic1
	_Screen.oImage.PictureVal = m.oComPic2
NEXT 
*//

*\\ whereas the next loop will break somewhere down the road:
FOR lnLoop = 1 to 100
	_Screen.oImage.PictureVal = m.oComPic1
	_Screen.oImage.PictureVal = m.oComPic1
	_Screen.oImage.PictureVal = m.oComPic2
	_Screen.oImage.PictureVal = m.oComPic2
NEXT

You will receive the following error, leaving you with a superficially valid COM object!

Believe me, that’s no fun to debug!

ToDOs

Now, we really have some work to do before displaying our COM images directly:

We have to get a device context handle
We have to get our current display resolution (DPI)
We have to know all about “dots per inch” and HiMetric units
We have to convert pixels to HiMetric units and vice versa (before we can use them)

The rest of this post is the content of my VFPX Help file project contribution.

LOADPICTURE([cFileName])

Parameters

cFileName
Specifies the image file on disk for which an object is created. The following image types are supported:

Image Type Groups	Filename Extensions
bitmaps	.bmp, .jpg, .jpeg, .jpe, .jfif, .gif, .giff, .gfa
icons	.ico
windows metafiles	.wmf
windows enhanced metafiles	.emf
cursor	.cur

Table 1 Supported Image Types

The following restrictions (tested with VFP 9 SP2 and OlePro32.dll Version 6.0.6002.18005) exist:

Image Type Groups	Restrictions & Issues
bitmaps	Loading .tif and .png formats will cause an OLE error.
icons	Icons are allowed with sizes up to 128x128 and must not have more than 256 colors. Even if there is more than one icon stored in the icon file, always only the smallest icon gets displayed. The icon file may contain much more icons - even with more colors and larger sizes - as long as there is at least one that complies with the rules above, then no exception is thrown.
cursor	Cursor files must not have more than 1K of file size, otherwise an OLE error is generated. Cursor files containing 16 color cursors can be loaded flawlessly, but only monochrome output is supported. Loading an animated cursor (.ani) causes an OLE error to be raised.

Table 2 Known Limitations

Null Picture Support

If cFileName is omitted, an uninitialized “null picture” object is returned.

You can include GETPICT( ) as cFileName to display the Open dialog from which you can choose a bitmap file.

Return Value

VFP’s LOADPICTURE() function returns a Picture type COM object reference that can be assigned to ActiveX controls and VFP’s Image object’s PictureVal property. However, the real primary interface iPicture only can be retrieved using code like this:

oIPicture = GETINTERFACE(LOADPICTURE(GETPICT()), "iPicture")

Remarks

Picture objects provide a language-neutral abstraction for bitmaps, icons, and metafiles. As with the standard font object, the system provides a standard implementation of the picture object. Its primary interfaces are iPicture and iPictureDisp. A picture object is created with OleCreatePictureIndirect and supports both the iPicture and the iPctureDisp interfaces. The OLE-provided picture object implements the complete semantics of the iPcture and iPictureDisp interfaces. In other words, there’s no need to use another interface than iPicture!

VFP’s LOADPICTURE() function internally wraps the OleCreatePictureIndirect() function implemented in OleAut32.dll. Thus, all you can read about that function (above and online) is also true for VFP’s LOADPICTURE() function. LOADPICTURE () was added to VFP’s vocabulary to make it easier to load images with COM interfaces that many presentation properties of ActiveX controls require for their settings. For example, the ActiveX Outline control has a PictureOpen property that requires a COM object image reference for its setting.

The COM object returned by VFP’s LOADPICTURE() function hides its primary interface iPicture. In contrast to the reference returnd by VFP’s LOADPICTURE(), the OLE-image’s primary iPicture interface is the only fully functional one. In other words, only iPicture can be used in VFP programms without generating any OLE errors. Because iPicture is a superset of Picture it may be, better, it should be used everywhere instead of the one returnd by LOADPICTURE() ! Example #1 in the examples section below proves that it makes no difference which OLE image interface gets assigned to a VFP oIMAGE.PICTUREVAL property.

The IID of the iPicture interface is defined as “{7BF80980-BF32-101A-8BBB-00AA00300CAB}”. Thus, the following two lines of code both create a null picture OLE image object:

oIPicture1 = GETINTERFACE(LOADPICTURE(GETPICT()), "iPicture")
oIPicture2 = CREATEOBJECTEX("StdPicture","","{7BF80980-BF32-101A-8BBB-00AA00300CAB}")

Interface Members

The following table summarizes the PEMs (with prefix P: = property, M: = method) of the iPicture interface. ‘Green’ PEMs are read/writable, all others are readonly.

PEM	Used for	ValueType
P: Attributes	The current set of the picture's bit attributes.	DWORD (int)
P: CurDC	The current device context into which this picture is selected.	HDC (long)
P: Handle	Handle to the picture managed within this picture object.	OLE_Handle (int)
P: Height	The current height of the picture in the picture object.	OLE_XSIZE_HIMETRIC (long)
P: hPal	The current palette of the picture (if any).	OLE_Handle (int)
P: KeepOriginalFormat	The current value of the picture object's KeepOriginalFormat property.	Bool
P: Type	The current type of the picture.	Short (int)
P: Width	The current width of the picture in the picture object.	OLE_XSIZE_HIMETRIC (long)
M: PictureChanged	Notifies the picture object that its picture resource changed.
M: Render	Draws the specified portion of the picture onto the specified device context, positioned at the specified location.
M: SaveAS File	Saves the picture's data into a stream in the same format that it would save itself into a file.
M: SelectPicture	Selects a bitmap picture into a given device context, returning the device context in which the picture was previously selected as well as the picture's handle.

Table 3 iPicture Interface Members

The Attributes property is said to hold the picture’s bit attributes. Actually, there are only two, which can be set alone, or additive. The following table lists both possible values:

Constant	Description	Value
PICTURE_SCALABLE	The picture object is scalable, such that it can be redrawn with a different size than was used to create the picture originally. Metafile-based pictures are considered scalable; icon and bitmap pictures, while they can be scaled, do not express this attribute because both involve bitmap stretching instead of true scaling.	1
PICTURE_TRANSPARENT	The picture object contains an image that has transparent areas, such that drawing the picture will not necessarily fill in all the spaces in the rectangle it occupies. Metafile and icon pictures have this attribute; bitmap pictures do not.	2

Table 4 PictureAttributes Enumeration

The following table lists all possible values of the iPicture.Type property:

Constant	Description	Value
PICTYPE_UNINITIALIZED	The picture object is currently uninitialized. This value will never be returned within VFP!	-1
PICTYPE_NONE	A new picture object is to be created without an initialized state. This value is returned from VFP if LoadPicture() is used without a parameter.	0
PICTYPE_BITMAP	The picture type is a bitmap.	1
PICTYPE_METAFILE	The picture type is a metafile.	2
PICTYPE_ICON	The picture type is an icon.	3
PICTYPE_ENHMETAFILE	The picture type is an enhanced metafile.	4

Table 5 Type Property Values

The most interesting method of the COM image object’s iPicture interface ist render() which also works flawlessly only when called on the iPicture interface. The following table summarises the parameters of the render() method:

Parameter	Used for	Scale Unit
hdc	A handle of the device context on which to render the image.	------
x	The horizontal coordinate in hdc at which to place the rendered image (X-position of upper left corner of output rectangle).	pixel
y	The vertical coordinate in hdc at which to place the rendered image (X-position of upper left corner of output rectangle).	pixel
cx	The horizontal dimension (width) of the destination rectangle (with of output rectangle).	pixel
cy	The vertical dimension (height) of the destination rectangle (height of output rectangle).	pixel
xSrc	The horizontal offset in the source picture from which to start copying.	HiMetric
ySrc	The vertical offset in the source picture from which to start copying.	HiMetric
cxSrc	The horizontal extent to copy from the source picture (width of image source’s clipping region AND direction of readout).	HiMetric
cySrc	The vertical extent to copy from the source picture (height of image source’s clipping region AND direction of readout).	HiMetric
lprcWBounds	If hdc is a metafile device context, the lprcWBounds parameter points to a RECTL structure specifying the bounding rectangle in the underlying metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same coordinate space. If hdcDraw is not a metafile device context, lprcWBounds will be NULL. If hdcDraw is a metafile device context, lprcWBounds cannot be NULL!	------

Table 6 Render() Parameter Galore

The method returns standard values like E_FAIL, E_INVALIDARG and E_OUTOFMEMORY, as well as S_OK, E_POINTER and CTL_E_INVALIDPROPERTYVALUE. These values are described on MSDN.

Applications

The render function has plenty of parameters. Some of them passing in pixel values, others HiMetric values. Example #3 has some useful conversions as well as other supporting functions and definitions. To figure out how render() works try the VFP code below; type it in line by line into VFP’s command window:

* locate an image with round about 100 x 100 pixels 
goPic = LOADPICTURE(GETPICT()) 
gIP = GETINTERFACE(m.goPic, "iPicture") 
goForm = CREATEOBJECT("Form") 
goForm.Show() 
* declare access to the _client_area_ of a window 
DECLARE Integer GetDC IN USER32 integer HWnd 
* hDC should be <> 0 (otherwise that's an error)! 
hDC = GetDC(goForm.HWnd) 
* render your image directly onto form's client area 
gIP.Render(m.hDC,0,0,100,100,0,gIP.Height,gIP.Width,- gIP.Height,NULL) 
* declare release function 
DECLARE Integer ReleaseDC IN USER32 integer HWnd, integer hDC 
* next line should print 1 on the form's background >> "Okay" 
? ReleaseDC(m.goForm.HWnd, m.hDC) 
* declare access to the _whole_ window 
DECLARE Integer GetWindowDC IN USER32 integer HWnd 
* hDC now references form's caption an border areas as well! 
hDC = GetWindowDC(goForm.HWnd) 
* render out partially overwriting form's border and caption 
gIP.Render(m.hDC,0,0,100,100,0,gIP.Height,gIP.Width,- gIP.Height,NULL) 
* never forget to free an allocated device context 
? ReleaseDC(m.goForm.HWnd, m.hDC)

Direct input into VFP’s command window

iPicture.Render() qualifies for painting on otherwise unreachable form regions, like titlebar or borders. Another interesting application for direct rendering stems from the fact that no VFP object reference is necessary for painting. The render() method solely uses a common windows handle. Thus, one can render on any known device context.

Drawback

iPicture.Render() does its work outside of - and unnoticed by – the VFP engine itself. That’s why VFP has no idea of what was painted “between the lines”. Each time VFP refreshes the form’s area (we’ve just rendered our picture onto), will clear out our image. To make rendered output persistent measures have to be taken against VFP wiping it out!

Examples

Example #1

The following example shows that both interfaces (Picture and IPicture) of a COM image instance can be assigned to VFP’s Image.PictureVal property:

PUBLIC goPic AS Object, goIPic AS Object
goPic = LOADPICTURE(GETPICT()) 
goIPic = GETINTERFACE(m.goPic, "iPicture") 
_SCREEN.AddObject("oPic1","IMAGE") 
_SCREEN.AddObject("oPic2","IMAGE") 
WITH _SCREEN.oPic1 
	.VISIBLE = .T.
	.PICTUREVAL = m.goPic && "Picture"-Interface 
ENDWITH
WITH _SCREEN.oPic2
	.LEFT = 110 
	.VISIBLE = .T.
	.PICTUREVAL = m.goIPic && "IPicture"-Interface
ENDWITH 
HIDE WINDOWS ALL 
WAIT WINDOW "Press any key..." 
_SCREEN.RemoveObject("oPic1") 
_SCREEN.RemoveObject("oPic2") 
STORE NULL TO goPic, goIPic 
CLEAR 
SHOW WINDOWS ALL

Example #2

The following example shows how to query the iPicture interface of a COM image instance. Intentionally, there are no Try…Catch…Endtry sections in this demo code, so that OLE errors may occur. You have to run the code snippet multiple times with different image types to see them.

goPic = LOADPICTURE(GETPICT()) 
IF VARTYPE(m.goPic) == "O"
	goIPic = GETINTERFACE(m.goPic, "iPicture")
	IF VARTYPE(m.goIPic) == "O" 
		CLEAR && just some informal output: 
		WITH m.goIPic 
			? 
			? "Properties of 'IPicture'-Interface:" 
			? "Attributes" ,.Attributes 
			*\\ next line will fail if an ICOn loaded 
			? "CurDC" ,.CurDC 
			? "Handle" ,.Handle 
			? "Height" ,.Height 
			*\\ next line will fail if an ICOn loaded 
			? "hPal" ,.hPal 
			? "KeepOriginalFormat",.KeepOriginalFormat 
			? "Type" ,.Type 
			? "Width" ,.Width 
			? 
		ENDWITH 
	ENDIF 
ENDIF

Example #3

The following code is a collection of supporting functions and declarations that come in handy while programming OLE image objects.

* Supporting Functions & DEFINEs
#DEFINE INCH2MILLIMETER 25.4 && 1 Inch = 25.4 millimeters
#DEFINE INCH2HIMETRICS (INCH2MILLIMETER * 100) && 1 HIMETRIC = 0.01
FUNCTION PXL2HIME(tnPixel AS Integer) AS Integer
	* Pixel to HiMetric conversion
	LOCAL lnPixelsOnOneHiMetricUnit AS Integer
	lnPixelsOnOneHiMetricUnit = INCH2HIMETRICS / GetDPI()
RETURN ROUND(lnPixelsOnOneHiMetricUnit * m.tnPixel, 0)
ENDFUNC
FUNCTION HIME2PXL(tnHimetric AS Integer) AS Integer
	* HiMetric to Pixel conversion
	LOCAL lnPixelsOnOneHiMetricUnit AS Integer
	lnPixelsOnOneHiMetricUnit = INCH2HIMETRICS / GetDPI()
RETURN ROUND(m.tnHimetric / m.lnPixelsOnOneHiMetricUnit, 0)
ENDFUNC
FUNCTION GetDPI(tnHDC AS Integer) AS Integer
      * retrieve dots per inch resolution 
      * for VFP's _SCREEN device context
	DECLARE Integer GetDeviceCaps IN GDI32 integer hdc, integer nIndex
	DECLARE Integer GetWindowDC IN USER32 integer HWnd
	DECLARE Integer ReleaseDC IN USER32 integer HWnd, integer hDC
	* For simplicity, we assume X- and Y- dimensions 
      * using the same DPI resolution.
	#DEFINE LOGPIXELSX 88 && Logical pixels/inch in X	
      #DEFINE LOGPIXELSY 90 && Logical pixels/inch in Y
	* Get VFP's _Screen-hDC to calculate resolution:
	LOCAL lhDC AS Integer, lnDPI AS Integer
	STORE 0 TO lhDC, lnDPI
	lhDC = GetWindowDC(_Screen.HWnd)
	IF NOT m.lhDC = 0
		lnDPI = GetDeviceCaps(m.lhDC, LOGPIXELSX)
	ELSE
		lnDPI = 96 && default to 96 DPI
	ENDIF
	* Free device context
	= ReleaseDC(_Screen.HWnd, m.lhDC)
RETURN m.lnDPI
ENDFUNC
FUNCTION GetCanvas(tnHWND AS Integer, tlChild AS Boolean) AS Integer
	* Retrieve hDC (handle DeviceContext) of window handle
	* tlChild = TRUE  := Use GetDC()
	* tlChild = FALSE := Use GetWindowDC()
	DECLARE Integer GetDC IN USER32 integer HWnd
	DECLARE Integer GetWindowDC IN USER32 integer HWnd
	LOCAL lnHDC AS Integer
	IF m.tlChild
		lnHDC = GetDC(m.tnHWND)
	ELSE
		lnHDC = GetWindowDC(m.tnHWND)
	ENDIF
RETURN m.lnHDC
ENDFUNC
FUNCTION ReleaseCanvas(tnHWND AS Integer, tnHDC AS Integer) AS Integer
	* Releases a borrowed hDC
	DECLARE Integer ReleaseDC IN USER32 integer HWnd, integer hDC
RETURN ReleaseDC(m.tnHWND, m.tnHDC)
ENDFUNC
* The following function is not bullet-proof, as it fails on forms with scrollbars ;
  (oForm.Scrollbars > 0) See Example #4 for a working solution!
FUNCTION GetChildAreaCanvas(tnhWnd AS Integer) AS Integer
	* VFP ‘TopLevelForms’ (oForm.ShowWindow = 2) have
	*      a secondary window inside the outer one.
	* This is also true for forms showing scrollbars!
	LOCAL lnVfpHANDLE AS Integer, lnClienthWnd AS Integer, lnHDC AS Integer
	* Convert the given Windows hWnd to an internal VFP WHANDLE
	lnVfpHANDLE = SYS(2326, m.tnhWnd)
	* Retrieve the Windows hWnd for a client window 
	* (WCLIENTWINDOW) of a specified Visual FoxPro parent window
	lnClienthWnd = SYS(2325, m.lnVfpHANDLE)
	* Check if there is a WCLIENTWINDOW
	IF lnClienthWnd = lnVfpHANDLE
		* No such WCLIENTWINDOW, return child’s client area
		lnHDC = GetCanvas(m.tnhWnd, .T.)	
	ELSE
		* There IS a WCLIENTWINDOW!
		* Get the device context handle for the 
		* whole client area of that window:
		lnHDC = GetCanvas(lnClienthWnd)
	ENDIF
RETURN m.lnHDC
ENDFUNC

Example #4

The following example demonstrates how to render an image on different types of forms. Copy the code to a PRG file, then compile and run it.

The first section of the program can be seen as a testing setup. You will be asked four times to select a picture from your local disk. Then, a form will be created and the chosen picture will be rendered inside it. The MyForm class definition holds all functionality. At the end of this listing there are three supporting subclasses of MyForm called MyScrollableForm, MyDockableForm, and MyTopLevelForm which gets instantiated to test all kinds of form types. You may want to run the demo several times while changing/varying the base form’s (MyForm) Scrollbars and MDIForm property values. In addition to that you may uncomment the DEBUGOUT lines in MyForm.HandleWinMsg1() and HandleWinMsg2() to watch WinMessages in your debugger. The method MyForm.ImageAttribs() is called at the end of MyForm.RetrievePicture() method. If you like to see additional information about the loaded image, uncomment the invocation there.

CLEAR
*** SET STEP ON 
RELEASE ALL LIKE goForm*
PUBLIC goForm1, goForm2, goForm3, goForm4
*//
*\\ Try rendering on a form in SCREEN
goForm1 = CREATEOBJECT("MyForm")	&& IN_SCREEN (MDIForm = .T.)
IF VARTYPE(m.goForm1) == "O"
	goForm1.Show()
	goForm1.Caption = "goForm1 => IN_SCREEN (MDIForm = .T.)"
	goForm1.Name = "goForm1"
ENDIF
*//
* SET STEP ON
*\\ Try rendering on a dockable form
goForm2 = CREATEOBJECT("MyDockableForm") && IN_SCREEN (dockable = 1)
IF VARTYPE(m.goForm2) == "O"
	goForm2.Show()
	goForm2.Caption = "goForm2 => IN_SCREEN (dockable = 1)"
	goForm2.Name = "goForm2"
ENDIF
*//
* SET STEP ON 
*\\ Try rendering on a TopLevelForm (TLF)
goForm3 = CREATEOBJECT("MyTopLevelForm") && AS_TOPLEVEL_FORM
IF VARTYPE(m.goForm3) == "O"
	goForm3.Show()
	goForm3.Caption = "goForm3 => AS_TOPLEVEL_FORM"
	goForm3.Name = "goForm3"
ENDIF
*//
* SET STEP ON 
*\\ Try rendering on a regular (child) form (with scrollbars)
goForm4 = CREATEOBJECT("MyScrollableForm") && IN_SCREEN (scrollbars = 3)
IF VARTYPE(m.goForm4) == "O"
	goForm4.Show()
	goForm4.Caption = "goForm4 => IN_SCREEN (scrollbars = 3)"
	goForm4.Name = "goForm4"
ENDIF
*//
RETURN && >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Bye, bye!

***********************************************************
*** SYS(602,0) && set off-screen bitmaps to "OFF"
*\\ 	setting of off-screen bitmaps may have some impact
*\\ 	but only, if one does not take care of all oddities.
*\\ 	!!!!! This demo program is side effect free !!!!!
*** SYS(602,1) && set off-screen bitmaps to "ON"
***********************************************************

DEFINE CLASS MyForm AS Form
	*\\ ----------------------------------
	AllowOutput = .F.	&& ? will be echoed on form while active
	ShowWindow = 0 	&& 0 := In Screen, 1 := In TLF, 2:= AS TLF
	Scrollbars = 0	&& 0 : = None, 1 := horizontal, 2:= vertical, 3 := both
	MDIForm = .T. 	&& .T. := form is a MDI form
	*\\ user defined ---------------------
	oPic = NULL		&& VFP's LOADPICTURE() COM object reference
	oIPic = NULL	&& promary iPicture interface reference
	cPicturePath = ""	&& full qualified DOS path to image
	lEventsBound = .F.&& flag
	nhDC = -1		&& device context to render the image on
	nHwnd = 0		&& window handle of rendering device context (.nhDC)
      *** HWnd = ....	&& thisform's native window handle which must not always
				&& be the window handle of the rendering device context!
	xDPI = 0		&& VFP's _SCREEN X-Resolution
	yDPI = 0		&& VFP's _SCREEN Y-Resolution
	iWindowProc1 = 0	&& Buffer 
	iWindowProc2 = 0	&& Buffer
	nWidth = 0		&& Ole-Image property: Image width (pixels)
	nHeight = 0		&&  dito : Image height (pixels)
	nTop = 0		&&  dito : Image top position (pixels)
	nLeft = 0		&&  dito : Image left position (pixels)
	nXOffset = 0	&&  dito : Horiz.Offset in source (where copying starts)
	nYOffset = 0	&&  dito : Vert.Offset in source (where copying starts)
	nCopyWidth = 0	&&  dito : Horiz.Extend to copy from + readout direction
	nCopyHeight = 0	&&  dito : Vert.Extend to copy from + readout direction
	*// ----------------------------------
	
	PROTECTED FUNCTION INIT() AS BOOLEAN
		*\\ call public implementation
		THIS.INITIALIZE()
		*// 
	RETURN .T. && always allow form to stay in memory
	ENDFUNC

	PROCEDURE INITIALIZE() AS VOID
		WITH THIS
			*\\
			.DeclareWinAPI()
			.RetrieveDPI()
			.RetrieveWinHandle()
			.RetrieveWinProcs()
			.RetrieveHandleDC()
			.RetrievePicture()
			.DoBind()
			*//
		ENDWITH
	ENDFUNC

	PROCEDURE PAINT() AS VOID
		*\\ common entry point to render our COM pictures
		THIS.RenderImages()
		*// Secondary entry points (even more important) see HandleWinMsg1 & 2
	ENDPROC

	PROTECTED PROCEDURE DESTROY() AS VOID
		WITH THIS
			.UnbindAll()
			.ResetAll()
			.ReleaseDeviceContext()
			*\\ release the public variable
			_SHELL = "RELEASE " + .Name
		ENDWITH
	ENDPROC

	PROTECTED PROCEDURE UnbindAll() AS VOID	
		UNBINDEVENTS(THIS)
		WITH THIS
			IF .lEventsBound
				*\\ restore form's message loop
				UNBINDEVENTS(.HWnd)
				UNBINDEVENTS(.nHWnd)
				*\\ .T. when BINDEVENT(hWnd,...) was successful
				.lEventsBound = .F.	
			ENDIF
		ENDWITH
	ENDPROC
	
	PROTECTED PROCEDURE ResetAll() AS VOID
		WITH THIS
			.oPic = NULL
			.oIPic = NULL
			.cPicturePath = ""
			.nHwnd = 0
			.xDPI = 0
			.yDPI = 0
			.iWindowProc1 = 0
			.iWindowProc2 = 0
			*\\ parameter for oIPic.Render()
			.nWidth = 0
			.nHeight = 0
			.nTop = 0
			.nLeft = 0
			.nXOffset = 0
			.nYOffset = 0
			.nCopyWidth = 0
			.nCopyHeight = 0
			*//
		ENDWITH
	ENDPROC
	
	PROTECTED PROCEDURE ReleaseDeviceContext() AS VOID
		*\\ Release .nHDC
		WITH THIS
			IF .nHDC <> 0 && handle of device context
				ReleaseDC(.nHWnd, .nHDC)
				.nHDC = 0
			ENDIF
		ENDWITH
	ENDPROC
	
	PROTECTED PROCEDURE DeclareWinAPI() AS VOID
	*\\ Register WINAPI declarations
	*\\ WIN32API: Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll, and Advapi32.dll
	    DECLARE INTEGER CallWindowProc	IN WIN32API INTEGER lpPrevWndFunc, INTEGER HWND,INTEGER Msg, INTEGER wParam, INTEGER LPARAM
	    DECLARE INTEGER GetDC 		IN WIN32API INTEGER HWND
	    DECLARE INTEGER GetDeviceCaps 	IN WIN32API INTEGER hDC, INTEGER nIndex
	    DECLARE INTEGER GetWindow		IN WIN32API INTEGER HWND, INTEGER wFlag
	    DECLARE INTEGER GetWindowDC	IN WIN32API INTEGER HWND
	    DECLARE INTEGER GetWindowLong	IN WIN32API INTEGER HWND, INTEGER nIndex
	    DECLARE INTEGER ReleaseDC		IN WIN32API INTEGER HWND, INTEGER hDC
	    *// some more unused (but useful) at the end of this listing
	ENDPROC

	PROTECTED PROCEDURE RetrieveDPI() AS VOID
	*\\ calculate X/Y _screen resolutions
	*\\ retrieves dots per inch resolution for VFP's _SCREEN device context
		#DEFINE LOGPIXELSX 88 && Logical pixels/inch in X
		#DEFINE LOGPIXELSY 90 && Logical pixels/inch in Y
		*//				
		LOCAL lhDC AS Integer, lnDPI AS Integer
		lhDC = GetWindowDC(_Screen.HWnd)
		IF m.lhDC <> 0
			THIS.xDPI = GetDeviceCaps(m.lhDC, LOGPIXELSX)
			THIS.yDPI = GetDeviceCaps(m.lhDC, LOGPIXELSY)
			= ReleaseDC(_Screen.HWnd, m.lhDC)
		ELSE
			*\\ fallback defaults
			STORE 96 TO ._xDPI, ._yDPI
		ENDIF
	ENDPROC

	PROTECTED PROCEDURE RetrieveWinHandle() AS VOID
		#DEFINE GW_CHILD 5
		WITH THIS
			*\\ default: THISFOEM.HWnd
			.nHWnd = .hWnd
			*//
			*\\ handle different scenarios:
			DO CASE
				CASE .Dockable > 0
					*\\ dockable forms do not have any child windows
				CASE .ShowWindow = 2
					*\\ If the parent form is a TopLevelForm then
					*\\	there must be another child window, thus
					*\\	drill down to get inner-most child
					.nhWnd = GetWindow(.nHWnd, GW_CHILD)
					*\\ TopLevelWindow with additional scroll bars
					IF .Scrollbars > 0
						*\\IF there are scrollbars enabled, there is 
						*\\an additional view port window. Thus,
						*\\drill down and get this window's handle
						.nhWnd = GetWindow(.nHWnd, GW_CHILD)
						*//
					ENDIF
				CASE .Scrollbars > 0
					*\\ Regular VFP form with scroll bars enabled
					.nhWnd = GetWindow(.nHWnd, GW_CHILD)
			ENDCASE
		ENDWITH
	ENDPROC

	PROTECTED PROCEDURE RetrieveWinProcs() AS VOID
		#DEFINE GWL_WNDPROC		(-4)
		*\\ retrieves the WIN Message handler ID for a given window 
		*\\ 	which defaults to THISFORM
		WITH THIS
			THIS.iWindowProc1 = GetWindowLong(.Hwnd, GWL_WNDPROC)
			THIS.iWindowProc2 = GetWindowLong(.nHwnd, GWL_WNDPROC)
		ENDWITH
		*//
	ENDPROC

	PROTECTED PROCEDURE RetrieveHandleDC(tlAll AS Boolean) AS VOID
		WITH THIS
			*\\ force parameter default to boolean FALSE
			IF NOT VARTYPE(m.tlAll) == "L"
				tlAll = .F.
			ENDIF
			*//
			IF m.tlAll
				*\\ the full window device context
				.nHDC = GetWindowDC(.nHwnd)
			ELSE
				*\\ the child area device context
				.nHDC = GetDC(.nHwnd)
			ENDIF
		ENDWITH
	ENDFUNC

	PROCEDURE RetrievePicture(tcFileName AS String) AS VOID
		*\\ Load picture from disk.
		*\\ Initializes .oPIC and .oIPIC
		IF (NOT VARTYPE(m.tcFileName) == "C")
			tcFileName = ""
		ELSE
			tcFileName = ALLTRIM(UPPER(m.tcFileName))
		ENDIF
		IF EMPTY(m.tcFileName)
			*\\ prompt user
			m.tcFileName = GETPICT("windows bitmap files:bmp;"+;
							"windows icon files:ico;"+;
							"run-length encoded files:rle;"+;
							"metafiles:wmf;"+;
							"enhanced metafiles:emf;"+;
							"JPEG files:jpg,jpeg",;
							"Render from file:", "Load" )
		ENDIF
		*\\ load the picture
		TRY
			loPic = LOADPICTURE(IIF(EMPTY(m.tcFileName), THIS.cPicturePath, m.tcFileName))
		CATCH
			loPic = NULL
		ENDTRY
		*//
		IF VARTYPE(m.loPic) == "O"
			WITH THIS
				*\\ save VFP's COM ref.
				.oPic = m.loPic
				*\\ save pimary COM pic ref
				.oIPic = GETINTERFACE(m.loPic, "IPicture")
				*//
				*\\ calculate pixel based width and height
				.nWidth = .HIME2PXL(.oIPic.Width, "X")
				.nHeight = .HIME2PXL(.oIPic.Height, "Y")
				.nTop = 0
				.nLeft = 0
				*//
				*\\ Next section positions a 1x1 pixel line object on the form
				*\\ at lower right corner of the rendered image. Scrollbars
				*\\ will appear if form is smaller than the picture loaded
				IF .Scrollbars > 0
					*\\ Make the scrollbars appear if secessary
					IF (.nWidth + .nLeft > .WIDTH) AND BITTEST(.Scrollbars, 0) OR ;
						(.nHeight + .nTop > .HEIGHT) AND BITTEST(.Scrollbars, 1)
						IF NOT PEMSTATUS(this,"_oPixel",5) 
							.AddObject("_oPixel","LINE")
							._oPixel.top = .nHeight + .nTop
							._oPixel.left = .nWidth + .nLeft
							._oPixel.DrawMode = 11 && NOP: In effect, this setting turns drawing off
							._oPixel.Visible = .T. && Must be set visible! Due to .DrawMode it is not rendered!
						ENDIF
					ENDIF
					*//
				ENDIF
				*//
				*\\ Want to echo some of the extended COM attributes?
				*\\	Uncomment next line (will echo to VFP's desktop)
				*** .ImageAttribs()
				*//
				*\\ finally render new image the 1st time
				.RenderImages()
				*//
			ENDWITH
		ENDIF
	ENDPROC

	PROTECTED PROCEDURE DoBind() AS VOID
		#DEFINE WM_ERASEBKGND	0x0014
		*\\ Bind to WIN-Messages
		WITH THIS
			*\\ the regular case: simple VFP form IN SCREEN
			BINDEVENT(.nhWnd, WM_ERASEBKGND, THIS, "HandleWinMsg2", 4)
			*//
			*\\ TopLevel form -or- simple form with scrollbars -or-
			*\\		a combination of both
			IF .ShowWindow = 2
				*\\ Some VFP forms receive "erase_background" message
				*\\		at their "outer" window
				BINDEVENT(.hWnd, WM_ERASEBKGND, THIS, "HandleWinMsg1", 4)
				*//
			ENDIF
			.lEventsBound = .T.
		ENDWITH
	ENDPROC

	FUNCTION HandleWinMsg1(tnHWnd AS INTEGER, tnMsg AS INTEGER, tnWPARAM AS INTEGER, tnLPARAM AS INTEGER) AS Integer
		**** DEBUGOUT "HandleWinMsg1 - WM_ERASEBKGND WPARAM = " + TRANSFORM(m.tnWPARAM) + " | LPARAM = "+ TRANSFORM(m.tnLPARAM)
		*//
		*\\ 1st Windows Message handler (either bound to outer TLF window or
		*\\		to the 'one & only' window handle >>> thisform.hwnd)
		LOCAL nRetvalue
		*\\ This routine gets called on Windows "EraseBackground" messages. 
		*\\	Thus, first forward the message (which will wipe out the background)...
		nRetvalue = CallWindowProc(THIS.iWindowProc1, m.tnHWnd, m.tnMsg, m.tnWPARAM, m.tnLPARAM)
		*\\ ... and finally, render our image(s) again
		THIS.RenderImages()
		*//
	RETURN m.nRetvalue
	ENDFUNC

	FUNCTION HandleWinMsg2(tnHWnd AS INTEGER, tnMsg AS INTEGER, tnWPARAM AS INTEGER, tnLPARAM AS INTEGER) AS Integer
		*** DEBUGOUT "HandleWinMsg2 - WM_ERASEBKGND WPARAM = " + TRANSFORM(m.tnWPARAM) + " | LPARAM = "+ TRANSFORM(m.tnLPARAM)
		*//
		*\\ 2nd Windows Message handler (bound to any inner window, if such one exists)
		LOCAL nRetvalue
		nRetvalue = CallWindowProc(THIS.iWindowProc2, m.tnHWnd, m.tnMsg, m.tnWPARAM, m.tnLPARAM)
		THIS.RenderImages()
		*//
	RETURN m.nRetvalue
	ENDFUNC
	
	PROTECTED PROCEDURE RenderImages() AS VOID
			*\\ output loaded COM image (4 times to demonstrate FXs)
		WITH THIS
			*\\ errors may rise during INIT() and DESTROY()
			*\\	it makes not much sense to catch them separately.
			*\\ Thus, just wrap all rendering with TRY...CATCH here
			TRY
				*\\ render the loaded picture 4 times:
				*\\ 1st: upper left one >>> normal output
				.oIPic.Render(.nhDC, 0, 0, .nWidth, .nHeight, 0,;
					.oIPic.Height, .oIPic.Width, - .oIPic.Height, NULL)
				*//
				*\\ 2nd: upper right one >>> mirrored vertically
				.oIPic.Render(.nhDC, .nWidth+10, 0, .nWidth, .nHeight, .oIPic.Width,;
					.oIPic.Height, - .oIPic.Width, - .oIPic.Height, NULL)
				*//
				*\\ lower left one >>> mirrored horizontally
				.oIPic.Render(.nhDC, 0, .nHeight+10, .nWidth, .nHeight,;
					0, 0, .oIPic.Width, .oIPic.Height, NULL)
				*//
				*\\ lower right one >>> mirrored horizontally + vertically
				.oIPic.Render(.nhDC, .nWidth+10, .nHeight+10, .nWidth, .nHeight, .oIPic.Width, 0,;
					- .oIPic.Width, .oIPic.Height, NULL)
				*//
			CATCH
				*\\ eat all rendering errors
			ENDTRY
			*//
		ENDWITH
	ENDPROC	
			
	PROCEDURE ImageAttribs() AS VOID
		*\\ only for testing
		WITH THIS
			IF VARTYPE(.oIPic) == "O"
				*\\ Output some interesting(?) things
				WITH .oIPic
					?
					? "Eigenschaften des 'IPicture'-Interface:"
					? "Attributes",.Attributes
					TRY
						? "CurDC",.CurDC
					CATCH
						? "No CurDC" && .ICO file
					ENDTRY
					? "Handle",.Handle
					? "Height",.Height
					TRY
						? "hPal",.hPal
					CATCH
						? "No hPal"
					ENDTRY
					? "KeepOriginalFormat" ,.KeepOriginalFormat
					? "Type"			,.Type
					? "Width"			,.Width
					?
				ENDWITH
				*//
			ENDIF
		ENDWITH
	ENDPROC
		
	#DEFINE INCH2MILLIMETER 25.4 && 1 Inch (German: 'Zoll') = 25.4 millimeters
	#DEFINE INCH2HIMETRICS (INCH2MILLIMETER * 100) && 1 HIMETRIC = 0.01 
	
	FUNCTION PXL2HIME(tnPixel AS Integer, tcDimension AS Character ) AS Integer
		LOCAL lnPixelsOnOneHiMetricUnit AS Integer
		lnPixelsOnOneHiMetricUnit = INCH2HIMETRICS / IIF(m.tcDimension== "X", THIS.xDPI,THIS.yDPI)
		*\\
		RETURN ROUND(lnPixelsOnOneHiMetricUnit * m.tnPixel, 0)
		*//
	ENDFUNC
	
	FUNCTION HIME2PXL(tnHimetric AS Integer, tcDimension AS Character ) AS Integer
		LOCAL lnPixelsOnOneHiMetricUnit AS Integer
		lnPixelsOnOneHiMetricUnit = INCH2HIMETRICS / IIF(m.tcDimension== "X", THIS.xDPI,THIS.yDPI)
		*\\
		RETURN ROUND(m.tnHimetric / m.lnPixelsOnOneHiMetricUnit, 0)
		*//
	ENDFUNC
	
	FUNCTION buf2dword(m.tcBuffer AS String) AS Integer
	RETURN CTOBIN(m.tcBuffer, "4rs")
	ENDFUNC
	*//
ENDDEFINE

DEFINE CLASS MyDockableForm AS MyForm
	Dockable = 1
	MDIForm	= .F.
ENDDEFINE

DEFINE CLASS MyScrollableForm AS MyForm
	Scrollbars = 3
	MDIForm	= .F.
ENDDEFINE

DEFINE CLASS MyTopLevelForm AS MyForm
	ShowWindow = 2
	MDIForm	= .F.
ENDDEFINE

*\\ unused defines and other useful declarations
*** #define WM_USER		 0x0400
*** #define WM_KILLFOCUS 0x0008
*** #define WM_PAINT	 0x000F

*\\ Unused, but useful WIN32API DECLAEs
* DECLARE INTEGER IsWindowVisible	IN WIN32API INTEGER HWND
* DECLARE INTEGER DefWindowProc		IN WIN32API INTEGER HWND, INTEGER Msg,INTEGER wParam, INTEGER LPARAM
* DECLARE INTEGER FindWindowEx		IN WIN32API INTEGER hWndParent, INTEGER hwndChildAfter, STRING lpszClass, STRING lpszWindow
* DECLARE INTEGER GetClassName		IN WIN32API INTEGER HWND, STRING lpClassName, INTEGER nMaxCount
* DECLARE INTEGER GetDesktopWindow	IN WIN32API
* DECLARE INTEGER GetWindowRect		IN WIN32API INTEGER HWND, STRING @lpRect
* DECLARE INTEGER GetWindowInfo		IN WIN32API INTEGER HWND, STRING @ pwindowinfo
* DECLARE INTEGER GetWindowText		IN WIN32API INTEGER HWND, STRING @szText, INTEGER nLen

2011-04-15T01:16:00.000+02:00

FoxQuill another VFP Framework

FoxQuill ( www.foxquill.de) is my own homegrown (and very private) framework I am working with. At the moment I’m enhancing and trying to migrate it to the .NET platform. At the same time I am learning C# – what a mess! Sometimes I think I am to old to start all over again with a new programming language. On the other hand, I believe that this new challenge could also be a good chance to create very interesting things…

Table of Content

FoxQuill will become FoxQuill.NET

Some thoughts and insights dealing with my private VFP-based framework (yep, I named it “FoxQuill”) and its future transition into the .NET world.

How To Re-Enable Blogger Comments (From Windows Live Writer)

2011-04-12T12:26:00.000+02:00

Version: 1.13.01 - last update: Wednesday, April 13, 2011, 11:55:00

WWW <= What Went Wrong :-)

I create & maintain this blog using Microsoft’s Windows Live Writer. Lately I was checking in some cool new sidebar gadgets for my blog space. During the update of my blogger template I must have changed a setting dealing with the display of comments at the bottom of each page.

How to reproduce

If you like to follow me, just do the steps below:

Check into your account
Click “Design” in the upper right corner of your blogger bar at top of the page (showing … <your login> [New Post] [Design] [Sign Out] )
Select the “Settings” tab and below click the “Comments” link.
All this brings you to the page shown below:

Img #1.) Be careful with the “Comments Default for Posts” entry!

The combo box in question allows you to disable the display of the 0 Comments link in the footer section of every new post. Setting this option to “New Posts Do Not Have Comments” will disable the whole commenting feature for every blog entry you will publish in the future!

Live Writer never knows

Sadly, our Live Writer is not aware of the fact, that comments are disabled. Thus, there is no way to correct the missing commenting option with the help of Microsoft’s tool. In addition, Google stores some kind of “comments-disabled” flag value inside of every post you make. Thus, you may re-visit your blogger’s settings page (shown above) and reset your wrong choice to “New Post Have Comments” like shown in the next screenshot:

But, this will not affect any page you posted while your wrong “…No Comments”-selection was active! Only your next new post will show the 0 Comments link again. Okay, you may consult Google’s help pages. There are a lot of FAQ entries dealing with “missing comments links”. Alas, that makes it not easier to find the right answer to solve your homegrown problem :-) Many times missing comments links resulting from some corrupted blogger template. There are plenty of suggestions how to manually fix broken templates. Maybe someone dares to follow them, but not me!

The RTFM Solution

There is a simple native way (only some clicks away!) to let the “Comments” link reappear in your post’s footer. I found it while reading some Google’s online help pages dealing with blogger settings, etc. If you like to follow me, just do the steps below:

Check into your account
Click “Design” in the upper right corner of your blogger bar at top of the page (showing … <your login> [New Post] [Design] [Sign Out] )
Select the “Posting” tab and below click the “Edit Posts” link.
All this brings you to the page shown below:

Img #2.) Select an entry with disabled Comments link!

Now, go and click “Edit” to switch a post with missing “Comments” link into edit mode. Google starts a web editor session for you like shown below:

Img #3.) Watch out the “Post Options” link in the bottom left corner!

There is an easy to oversee switch “Post Options” in the lower left corner of the online editor. Click that link-button and the editor window expands a region showing you a whole bunch of additional post related options, like shown below:

Img #4.) Choose “Allow” to re-enable “Comments”

Re-select “Allow” in the “Reader comments” option group and after saving your post shows up with n Comments link in it’s footer, again – finally ;-)

Repeat the last steps for every post with hidden/disabled “Comments” link – et nous voilà arrivés!

BTW.: The option used above (the way to change settings on a per-post basis) is well described somewhere on one of the many, many Google online help pages:-) We all know the shortcut “RTFM“, don’t we? ;-)

That's all for now,
CU guys!

A Native TreeView (Part V)

2011-04-12T11:28:00.001+02:00

Version: 1.01.05 - Last Update: Tuesday the 12th, April 2011 - 11:25:00

FoxPro Rocks! This is all about how to create complex controls using native VFP only!

Intro

**After all, the TreeShow must go on now…**

Last year I decided to publish some VFP demo application without source code you still can find here. The only reason for not supplying you with the VFP source code was, I dropped those fully functional sources somewhere (on an old memory stick) and didn’t remember exactly where I dropped that one… As I started working on a new (improved!) version of my native VFP-TreeView, I only was able to recover the compiled demo app which is using an outdated driver table structure and many more odd things. Well, in between I decided not to create a PRO-version (available only for a fee) but publish my final release under a Creative Commons License. I hope you will enjoy it!

The long and winding road…

During the last years I worked on some more or less challenging projects. One of those was (and still is) my implementation of the (one and only?) Native VFP-TreeView. I’m sorry but I have to tell you (again) that there is no “final thing” at the end of this post waiting for you – nope, still no final download is available! Instead, we have to talk about some features and (interesting?) aspects of my final implementation, first. Believe me, I’m going to show you some really cool stuff in the next chapters. I am sure you will benefit from some tips!

Back to school!

After I went back to the drawing board I started thinking about how to approach the pending performance optimization issues. As I told you, those days the number one reason to rethink my first approach was the lack of speed when working with large datasets; the bigger the record count of the driving cursor, the slower most of the collapse/expand actions became. Another bottleneck was the complexity of the tree item class. The more features I implemented there, the more time was wasted during refresh/repaint for jumping through endless IF…ELSE…ENDIF and other DO CASE constructs just to find out which part of the object had to be made visible or hidden or re-colored and so on. Finally, I got stuck with a wonderful implementation of a cool looking tree item class (with dozens of features) that ate up too much refresh-cycle time.
More than ten visible TreeView items rendered my good looking tree useless. At that point in time I knew two things: 1st., It was possible to build a native VFP TreeView and 2nd.: it was abundantly clear that some extraordinary speed optimizations had to be applied to the key parts of the design.

Let’s examine the “roots”!

My initial idea to use a VFP GRID class as the basic container vehicle, I didn’t want to discard. Thus, I couldn’t discard using a driving cursor, either. The driving table/cursor was the logical starting point of my speed optimization efforts, then. If you read Part IV-b of this thread, you should have seen my old driving table structure which was pretty complex. The tree cursor got more and more columns over times, but the first 5 columns of my driving table’s structure listing in Part IV-b dealt with the hierarchical aspects of tree display.
Well, we all know how to setup and store parent-child relationships of hierarchical related data in a dbf table, don’t we? I’m sure, you recognize the fields of my driving cursor immediately: pNodeID and pParentID hold the primary and foreign key values implementing that parent-child aspect.

The entries shown in the browse window above correspond to the screenshot of my demo TreeView in Part VI-b below.

As long as we are using a Microsoft ActiveX TreeView control storing the relationship within two columns (one holding the primary key and the other holding the grouping/parental foreign key) is sufficient. There are several ways to reload the parent-child information of such a cursor back into an ActiveX TreeView: you may want to use a couple of SQL-Select statements within a recursive SCAN loop to select all sets of child entries to fill up your TreeView. Again, there are other ways to refill an OLE-TreeView, it is up to you to decide what approach fits best within your environment!
Now(!) Try to create a native VFP index that can be employed with SET ORDER TO to display the node records (shown above in the browse window screenshot) in hierarchical sorted sequence like in the screenshot below (where I SET OREDER TO ‘piorder’)!

This should be the resulting browse window after your “very special” - index is active

Any ideas? I’m waiting!
I’m waiting!
I’m still waiting!
Again, I’m still waiting!
Right, you are! Without having a single sort order column containing sorting expressions in the correct hierarchical sequence there is no easy trick to solve our dilemma! The following source code fragment shows my old implementation to rebuild the Piorder column values of my driver table:

*\\ Rebuild_SortOrder() gets called from .RebuildMetaData() or recursively(!)
*\\
LPARAMETERS tcParentID As String, tiOrderNo As Integer @
   *\\      tcParentID :== id of parent node for which all children are processed now
   *\\      tiOrderNo :== next Piorder value to be set (passed in by reference!)
IF this.lReadOnlyMetadata
   RETURN
ENDIF
*//
*[BS]: NOTE>> No parameter checking any more coz we'll have done that
*\\ already in interface method "this.RebuildMetaData()"!
*\\
LOCAL lnRecNo AS Integer ,;
      lnOldRecNo AS Integer ,;
      liIndent AS Integer
*//
*\\ remember from where we started
lnOldRecNo = RECNO()
*//
*\\ Set OrderNo for current record
REPLACE PiOrder WITH m.tiOrderNo
*//
IF THIS.lSort && sub-sort children on PCCAPTION string
   SET ORDER TO PCCAPTION
ENDIF
*\\ process all children on the same level (siblings)
SCAN ALL FOR Pparentid == m.tcParentID
   *\\ increment sort order value
   tiOrderNo = m.tiOrderNo + 1
   REPLACE Piorder WITH m.tiOrderNo
   *//
   *\\ remember record number
   lnRecNo = RECNO()
   IF Pichildcnt > 0
      *\\ drill down recursively
      THIS.Rebuild_SortOrder(Pnodeid, @m.tiOrderNo)
      *//
   ENDIF
   GOTO RECORD (m.lnRecNo)
   *//
ENDSCAN
IF THIS.lSort
   SET ORDER TO
ENDIF
*//
GOTO RECORD (m.lnOldRecNo)
RETURN

Those days I did not change the cursor structure, but tried to solve the hierarchical-sorting problem using a more or less pragmatic approach. Sure you already can see the weakness of my solution:
Adding new items to the TreeView (into the cursor) results in a, at least partial, rewrite of the Piorder column. The closer to the root element an item is inserted, the more Piorder value REPLACEments have to be done. Typical “CRUD” ( Create, Replace, Update, Delete) operations can get really sluggish when applied to large TreeViews (with a lot of nodes > 10.000). On the other hand, my Rebuild_SortOrder() method is the perfect place to implement any additional sub-sorting (optional, I’m sorting all sibling child-nodes based on their caption).

All for One, One for All

If we, at least, want to dynamically retrieved each node caption from our driving cursor, then our three musketeers (Pnodeid, Pparentid and Piorder) finally meet D’Artagnan (Pccaption). Thus, my first approach started with a “four column minimum” driving table. Many more supporting columns were added to (1)speed up the TreeView refresh. Other column were added to (2)enhance flexibility at runtime. Columns such as Piindent and Pichildcnt belong to the first group; if we always instantly know how many levels deep a given node has to be “indented” before it can be displayed, this can be a big timesaver compared to always re-compute the indentation level for all tree nodes. Same is true for knowing about the number of children a tree node has. If we know the node’s child count during refresh in advance, this speeds up things a lot, especially, if we know that a given node doesn’t have any children (Pichildcnt == 0).
In contrast to Microsoft’s ActiveX TreeView control we cannot store additional information inside each node object itself, because each VFP node object is a single class instance that is shared inside a grid column between all rows (roughly speaking:-). To get closer, let’s eye the checkbox implementation. If we have our TreeView displaying checkboxes before each of it’s nodes, we can query the checked-state of each node object. This true/false value is stored in a property of each node object of an ActiveX-TreeView directly. An ActiveX-TreeView with, let’s say, 1000 nodes has 1000 node objects each capable of storing the checked/unchecked information on its own.
In contrast, our native VFP TreeView has only one real node class instance. The other 1000 nodes of our TreeView grid are virtual class instances only. They only get painted during refresh sharing the one and only real node object as some kind of punching tool for that. Since all node objects are more or less virtual, they must hold their “property” values stored in the fields of the corresponding (1000) rows of the driving cursor to make them persistent. That’s exactly what a VFP grid originally was designed for: display data stored in a cursor (an not property values of object collections :-)
The screenshot below shows some of the additional columns that were added later in the game. BTW: the Pnmark column just stores the checkbox values just discussed. As my native VFP TreeView can have OptionGroups (the famous radio button groups) the Pnmark column accepts values greater then 2 (to be able to hold radio button groups of any member-count).

Finally I’m going to explain another column “Pllastitem” you can see in the above screenshot. This flag (true/false) is used to simplify the implementation of the tree-lines algorithm a little bit. Below, you see a part of the screenshot my TreeView-Editor TreeView. The so called “Last items” are marked with red circles. The grid rows containing those definitions (see above) show the flag value 1 in their Pllastitem field.

A “last item“ is the last node on it’s indentation level. Either, the following node (the one with Piorder+1) is a child node (then that node’s Piindent value is higher), or it is a sibling of the “last item’s node” parent node (then that node’s Piindent value is lower). There are two other extremes: either there is no next node, then our “last item” node is the last node of the whole TreeView (with the highest Piorder value), or it is the first node in the TreeView, a so called root node (with the lowest Piorder value). If the node in question is a real “last item” node, then the vertical tree line of the indentation level ends on that grid row and must only be drawn to the mid of the row. Otherwise, for all other items, the grid line on the level has to be continued down to the next row. Watch the red circled spots to get the clue. Well, how would you implement fast refreshing vertical and horizontal tree lines up to over 30 levels of indentation? Either you drop all these lines like Vista explorer does (see below :-)

… or you have to store the needed information (is the current node the last on it’s own/current indentation level) in a separate column of your driving table. Next you have to figure out when and how to update that information. I leave it to you to check my implementation shown below.

*\\ Rebuild_LastNodeFlag()
*\\
*\\ Note: any ORDER that was SET gets released on exit!
*\\
IF this.lReadOnlyMetadata
   RETURN
ENDIF
*//
LOCAL lcParent AS String ,;
      liIndent As Integer ,;
      lnRecNo  AS Integer

*\\ Important: BLANK ALL PlLastItem metadata column entries first!
*\\          BITTEST(pbit_state,4) := exclude root node(s)
BLANK FIELDS Pllastitem ALL FOR NOT BITTEST(pbit_state,4)
*//
*\\ This gets a little bit tricky now:


SET ORDER TO PIORDER DESCENDING && TreeView definition now upside-down
GO TOP && we are on the last TreeView node now *\\ Scan from bottom to top!
*\\ ISBLANK() serves as a "virtual" flag field value: “not visited”
SCAN ALL FOR ISBLANK(Pllastitem)
   lnRecNo = RECNO()
   lcParent = Pparentid
   liIndent = Piindent
   *\\ Two simple rules apply here:    
   *\\ 1st: The last node (the one with the highest Piorder value) of each level of indentation must 
   *\\      be flagged TRUE in Pllastitem field!
   *\\ 2nd: Each trailing sibling node (all nodes with the same Piindent value and the same Pparentid 
   *\\      value that have a Piorder value less than the current node) can NOT be the "last-node"
   *\\ Thus:
   *\\    Running from bottom to top traversing our metadata cursor processing only BLANKed fields
   *\\    the first node record we'll find has to be the "last-node" of his 
   *\\    indentation level/(child)group.
   REPLACE Pllastitem WITH .T.
   *\\ Now skip from the bottom of the TreeView cursor "up" one line due to DESCENDING ordering
   SKIP
   *\\ from there walk up the TreeView definition and replace all sibling nodes’ Pllastitem 
   *\\ field with .F. (coz they all belong to the same group of siblings of our just flagged 
   *\\ “last node” in the code above). Writing .T. or .F. to the cursor clears the BLANK state.
   *\\ This will exclude the group of sibling nodes just processed from the next SCAN loop
   REPLACE REST Pllastitem WITH .F. FOR Pparentid == m.lcParent AND Piindent = m.liIndent
   *\\ finally reposition record pointer (set back to initial position >> last TreeView node)
   GOTO RECORD (m.lnRecNo)
   *// That's it. The SCAN now again goes "up" the treedef cursor until it finds another 
   *// BLANK record (group). Otherwise we're done.
ENDSCAN
*\\
SET ORDER TO

Wherever there is light, there are shadows

After all those days and nights I’ve tried to create an (almost) perfect native VFP TreeView, I can say, that both types (the ActiveX AND the native VFP one) have their pros & cons! I don’t want to repeat all OLE-control related facts I already talked about in the past in detail. Today I want to concentrate on the downsides a VFP Grid-based solution has. To make a long story short:
Displaying & manipulating hierarchical ordered records (based on a one-to-many parent-child relationship) with good performance using a VFP GRID definitely is no straight forward task! Below you see a screenshot of VFP’s document view window with my so called ‘DynaGridController’ class opened in VFP’s class designer. The dynaGridController is the workhorse class “behind the scenes“ that implements (and encapsulate) all basic TreeView engine behavior.

A lot of functionality only is necessary to collapse/expand tree nodes, to indent items correctly, to navigate the TreeView using keystrokes and other stuff. I am sure, the implementation of most of all these ‘odd things’ was much easier for Microsoft while creating their ActiveX version!

What comes next

Next time I will present you my own “hierarchical indexing” technique. You can utilize a slightly varied version of it when working with SQL Server 2008. Yep, they got it there, too! But you can only see there how to use it. I will show you how to implement it! The tricky and (copyright) protected part is, that you do not have to use multiple fields to create a TreeView like hierarchical sequence! Be prepared to learn something new ;-)

<To be continued…>