Skip to content

Global / Desktop Methods

Functions and Procedures Defined at the Desktop

DataFlex has always supported the placement of methods on the desktop. Even among our most experienced developers, the meaning of a "desktop method" has been a source of great confusion. In DataFlex 8.3, we changed the syntax of desktop methods to make their use and purpose clearer. The older syntaxes for supporting desktop methods are still supported, but they will be phased out in future DataFlex versions.

DataFlex supports two suggested methods for handling methods on the desktop. They should either be marked DESKTOP or GLOBAL.

Global Functions and Procedures

Function MyGlobalFoo Global Integer i Returns String

The "Global" syntax remains unchanged. If a function or procedure is marked as being Global, it is actually not a method at all. It is a function or procedure, which is accessed outside of any object considerations. A global function/procedure can be defined anywhere in an application and it can be defined one time only. Once a name is assigned to a global function or procedure, that name cannot be used for any other class and object methods. In other words, object methods and global functions/procedures cannot have the same name and will result in a compiler error.

We recommend that global functions and procedures be used sparingly. In an object-based system, you should use methods. This information, syntax, and advice is not new.

Desktop Methods

Function MyDesktopFoo Desktop Integer i Returns String

If the word "Desktop" immediately follows the method name, then this method becomes a method of the desktop object. The desktop object is the container object for all other objects in DataFlex. Desktop methods can be resolved either by sending the method directly to the Desktop or by delegation (assuming the objects within the desktop object all support delegation and the method is not understood by some other object).

// The method is resolved by sending directly to the desktop
Get MyDesktopFoo of Desktop iVal to sString

// The method will be solved by delegating to the desktop
Get MyDesktopFoo iVal to sString

Note that the Desktop syntax is new. Also, this syntax is different from using the old "for Desktop," a syntax which is highly discouraged.

Like the Global keyword, the Desktop keyword can be used anywhere to mark a method as a desktop method. Desktop methods are object-based methods. Therefore, you can use this name for a desktop method and use the same name for any other object or class you wish.

We also recommend that desktop methods be used sparingly. If your application contains many desktop methods or many global functions/procedures, you may wish to review your program structure. You may be creating code that is not properly encapsulated.

Ambiguous Desktop Methods in Existing Applications

We suggest that all methods that are coded at the desktop level (i.e., methods not contained within any other class or object) be explicitly marked as being GLOBAL or DESKTOP. All other syntaxes are considered either obsolete or not recommended. In particular, previous versions of DataFlex allowed methods placed on the desktop to contain no special marking. We refer to this as an "ambiguous" desktop method:

// If this were on the desktop, it would be considered ambiguous
Function MyDesktopFoo Integer i Returns String

We now discourage the use of ambiguous desktop methods. In 8.3, all old syntaxes were supported, including ambiguous desktop methods. They worked exactly as they did in all prior versions of DataFlex. However, using ambiguous desktop methods is now strongly discouraged. Beginning with DataFlex 9, ambiguous desktop methods generate error messages. Therefore, we advise that you start changing your programs now.

A compiler command, Compiler_Desktop_Method_Warnings On|Off, will allow you to control warnings and will default to off. The default is On, and you will either have to adjust your code (strongly recommended) or explicitly relax the compiler by setting this off. This can be turned on and off in sections of code to allow an orderly migration.

Ambiguous methods on the desktop are ambiguous. No matter how hard everyone tries to understand this, there is still far too much confusion. Some developers think they are (or should be) global methods, some developers think they are (or should be) desktop object methods, and some developers think they are for cObject (and should not be). By forcing developers to explicitly define desktop methods as being Global or Desktop, program intent will become clear.

Upgrading Existing Applications

All of the changes remain 100% compatible with existing code. You should plan on upgrading your code. The following rules should make this upgrade simple:

  1. Search for all occurrences of for DFDesktop and change to Desktop.

e.g. 

Procedure MyFoo for DFDesktop Integer iInt ---> Procedure MyFoo Desktop Integer iInt

Using for DFDesktop was the old way to define methods for the desktop. You now want to use the newer syntax.

  1. Search for all occurrences of for Desktop and for BaseClass and change them.

If you want these methods to behave exactly as they did prior to VDF8.3, you will want to change all of these to for cObject. cObject is the new base class that all DataFlex classes derive from. While cObject will give you the exact same behavior, this may not have been your intention. By using cObject, you are adding this method to the base class, which means that all classes and all objects directly understand this method. We generally advise against the for ClassName technique and we are strongly against using this for the ultimate base class, cObject. By doing this, you are changing the base behavior of all objects—a technique that can easily create unwanted side effects. So before changing this to cObject, you may wish to verify that this is really what you want to do. Often, defining this as a desktop method (e.g., change for Desktop/BaseClass to Desktop) will yield the desired result.

  1. Turn on compiler warnings for ambiguous desktop methods and make changes as needed.

Add the following command to the top of your program and compile:

Compiler_Desktop_Method_Warnings On

This will cause the compiler to report all ambiguous desktop methods. The Studio will present a list of all of these errors. You can now review each one of these and make them non-ambiguous.

You will either be changing these to DESKTOP or for cObject. Technically, an ambiguous method on the desktop is for cObject. However, this is very often not the intent of the programmer. The programmer probably wanted this to be a method for the desktop. If this was your intention, change this to DESKTOP. If your intention was to create a method that was directly understood by all objects in your application, change this to for cObject. While using for cObject will make your application behave exactly as it did before, this may not have been your intention, and this is not a recommended technique.

Desktop methods in general should be avoided. When used as for cObject, it should be highly avoided. When used as Global, it should be avoided. And even the use of for cDesktop should be minimized. The bottom line is, if we allow methods on the desktop to remain ambiguous, it will cause problems. When reviewing someone else's code, you will never be sure what their true intent was. And, even when fully understood, they are going to be a source of programming error. They should be avoided.

We advise you to review your code and change all of your ambiguous desktop methods to be explicitly for cDesktop, for cObject, or Global. We also encourage you to think about moving these methods somewhere else (maybe inside your panel) and we 1) strongly discourage the use of for cObject, and 2) discourage the overuse of for cDesktop, just like we discourage the overuse of Global. If you follow these recommendations, all ambiguity disappears.