Print Article

Seite 1 von 5

Issue Date: FoxTalk July 1997

Using VFP 5.0 Top-Level Forms

Richard A. Schummer www.rickschummer.com

Top-level forms open Visual FoxPro developers to a variety of opportunities. In this article, Rick gives you the low-down on this new type of form and describes some of its potential uses.
One of the most requested interface capabilities in the past few years has been the ability to provide single document interface (SDI) forms, and they're here in Visual FoxPro 5.0. Also known as top-level forms, they run outside of the Visual FoxPro frame or main window. Each SDI form is independent and appears separately on the Windows desktop. This article will introduce you to the new top-level forms, explain what you need to do to create a top-level form, and describe how to use some of the new menu capabilities associated with top-level forms. Finally, I'll discuss some implementations of this new capability. General overview A top-level form is a modeless form that runs without a parent form. It can appear in front of or behind other Windows applications, including Visual FoxPro. Each instance of a top-level form will appear on the Windows taskbar and can contain child frames as well. The VFP Debugger application is an example of an SDI Form. The main Debugger window can be configured to run outside the VFP main window by setting the Environment drop-down list box (in the Debug tab under Tools, Options) to Debug Frame. When set this way, several child forms are contained inside the Debugger "form." Another example of a top-level form is the Windows Help System. The help system also spawns other top-level forms for searching and the glossary. Form ShowWindow property The ShowWindow property is the only form property you need to set to make the form a top-level form. Three settings are available:

Value 0 1 2

Setting In Screen In Top Level Form Top Level Form

This property defaults to 0, which means all application forms will run inside the VFP frame. To make the form run outside the VFP frame, set this property to 2. Try running a form and you'll notice that you can move the form outside VFP. You could also do this in VFP 3.0b using the Desktop form property. The main difference between the ShowWindow and Desktop properties appears when the VFP frame is minimized. If the Desktop property is used, the form disappears when VFP is minimized. If the ShowWindow setting is used to create a top-level form, the form will remain visible even when the VFP frame isn't visible. With the ShowWindow property, each SDI form also gets a separate entry in the Windows Taskbar. This doesn't happen with the Desktop property. Hiding the main VFP window So you just built your first SDI form after reading the first part of this article and now you're thinking "What a powerful capability this is!" Several seconds later, you wonder, "How do I get rid of the VFP frame?" There are two ways to accomplish this. The first is a new VFP configuration setting called SCREEN in CONFIG.FPW. Just place the following line in the application's CONFIG.FPW: SCREEN = OFF This setting is critical if you want your applications to have a shrink-wrap look and feel. This is the only way to remove the VFP frame during application startup. It's important to note that this setting works differently with the development version of VFP. VFP is still displayed after the initial startup, but it isn't visible while Visual FoxPro boots or while a startup program called from CONFIG.FPW is running. The second method is useful if you want to hide VFP when an SDI form is executed inside the development environment. To accomplish this, place any of the following lines of code in the Form.Init() method: Application.Visible = .F. or

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06

Print Article

Seite 2 von 5

_VFP.Visible or _SCREEN.Visible

= .F.

= .F.

To redisplay VFP when the form is shut down, place any of the following lines of code in the Form.Destroy() method: Application.Visible = .T. or _VFP.Visible or _SCREEN.Visible = .T. = .T.

If you don't make the main VFP frame visible with this second batch of code, you'll return control to an invisible session of VFP when the form is closed. This is impossible to reinstate; you'll have to end the task or reboot. The application object (Application, or _VFP ) is an object reference created for each instance of Visual FoxPro. This exposes properties and methods for each application. You can also use _SCREEN, as you did back in the days of VFP 3.0. Where to use top-level forms Now that you have all this new information to create really cool forms, how can you use this technology to better your customers' applications? So far, I've found five uses: application splash screens, extended legacy applications, launcher forms, a replacement for _SCREEN, and Visual FoxPro developer utilities. Splash screens The splash screen is the most obvious use for top-level forms. For developers who aren't familiar with splash screens, they're the forms that are displayed immediately when an application is started to keep the user occupied while the rest of the application is loading (see Figure 1). Their purpose is typically to distract users from noticing the lag time that occurs before applications are ready to use. By using SCREEN = OFF in the CONFIG.FPW and an SDI form you can create a start-up process that mimics many shrink-wrapped applications. Figure 1: Splash Screen.

The accompanying Download file includes a form called SPLASH.SCX, which demonstrates how to build a splash screen. Here are a couple of quick notes about this form: Obviously I set the ShowWindow Property to "2 -- As Top-Level Form," but several other form properties give this type of form a style, like many shrink-wrapped packages we buy: ShowWindow AutoCenter BorderStyle Caption ControlBox Closable MaxButton MinButton Movable AlwaysOnTop = = = = = = = = = = 2 .T. 0 "" .F. .F. .F. .F. .F. .T.

Most of these properties are self-explanatory, such as no caption, no close button, no minimize and maximize buttons, and no control menu. So why is the Movable property set to false? This was set to remove the title bar at the top of the form. It took me awhile to figure this out; I hope my discovery saves you some frustration. Extended legacy applications How many times has one of your customers asked for new functionality in a legacy application? He or she may want to update a FoxPro 2.x application that has been running in production for quite some time; and you may already be working on the customer's next killer application in Visual FoxPro. If you've been developing in VFP for a while you may find it difficult to use

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06

Print Article

Seite 3 von 5

FoxPro 2.6 DOS for Windows, but the customer is willing to pay. To keep your customer satisfied, you agree to extend the functionality. What if you could add the functionality using Visual FoxPro without rewriting the entire application? One example of this is a postal code search routine I developed for my wife. She maintains a customer list for a small company using a FoxPro application developed in FoxPro 2.6 for Windows. Because I didn't have time to deal with the intimate details of the application and she wanted to incorporate a postal code lookup routine, I quickly developed an SDI form that runs as a standalone app. She continues using the FPW 2.6 app and runs this quick SDI form to perform her lookups. Now she can copy the postal code or city to the Windows clipboard and paste it into the customer data entry form. This is a unique way to incorporate Visual FoxPro technology into legacy applications without rewriting the entire system. In my case, I didn't have time to convert the old application and didn't want to write version 2.6 code. One drawback to this type of extension is that the machine will load both the FoxPro for Windows code and the Visual FoxPro code at the same time, which could be a problem on machines with only 8M to 12M of memory. Launcher forms One neat idea, which was presented during beta testing of VFP 5.0, related to SDI forms: A "launcher form" (see Figure 2 ) consists of an SDI form with CommandButtons or icons that can be clicked to run other forms. This is one kind of menu interface that can be presented to a client without using conventional menus. It's also a way to present a Windows 95 or Windows NT 4.0 Explorer interface in your custom applications. An example of this type of interface is the Windows Control Panel. Figure 2: "launcher form".

I built a simplified example of this concept in an application called SDIART.EXE, which is also included with the Download file. This application starts by presenting a launcher form. Clicking on the different forms in the ListView object will execute the other SDI forms. The ListView object is populated with all the forms that are in the default directory. You can add new forms by simply dropping a new form file in the directory. This may not be the ideal way to extend a customer's application, but it shows the power of the "launcher" concept. This launcher form contains a top-level menu (see the sidebar "Top-Level Menus") that's used to control the form. Accordingly, the File . . . Exit menu option must be used to terminate SDIART.EXE. Simply closing the form will close the launcher form without terminating the EXE program. (If you close the form by mistake, use the Program . . . Cancel menu option in the VFP menu.) _SCREEN replacement Replacing the _SCREEN simply involves building a top-level form that houses the application. This top-level form contains a top-level menu and one or more child forms. These child forms are designed the same way as in VFP 3.0 except that they become child forms of the top-level forms. What are the advantages of building a replacement for the _SCREEN? The primary advantage is that you can add custom properties and methods to a top-level form, while you can't modify the _SCREEN object. This is a very powerful capability. One use I've read about is adding code to the "application" window Resize() or Click() methods. If the application window is resized you might want to perform some action. None of these methods exists for the _SCREEN object. Visual FoxPro utilities I often use SDI forms for interactive development utilities that I want to run separately from the development version of VFP. It keeps the VFP frame clean and allows the application to be quickly accessed from the taskbar when I need it. I start the utility once and let it run in the "background." One example of these utilities is the Hex Editor that ships with Visual FoxPro. I wrote a utility called Hack VCX/SCX. Have you ever renamed a Visual Class Library? I can already hear your groans and see the looks of terror on your faces. What happens next? Try opening a form that has objects you renamed in the class library and you'll get this message: "Error instantiating class. Cannot find in ." Sure, you can locate the renamed classes and display the form in the Form Designer. Then if you close the form and open it up again, you'll see the locate dialog box again. Even though you pointed the object to the correct class, the Form Designer never noted that the form changed to kick in the Save logic when closed down. This sounds like a bug to me. You can change the form yet again to work around this. Even more aggravating is that every object that was renamed (or if the class library was renamed) will spawn the locate dialog box. The same dialog box is displayed over and over even if the new class or class library was located before. This can be quite frustrating after the first five changes.

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06

Print Article

Seite 4 von 5

So what happens when something goes wrong and you need to get inside the .VCX or .SCX? You can USE the file and browse it. Unfortunately, all the information you want to see is stored in memo fields. Then you have to look for all the fields you want to look into, resize them, move them elsewhere so the information is viewable, and so on. The next time you open the file with a BROWSE LAST, the file will be okay, but a new class will cause you this grief all over again! I built the Hack VCX/SCX form (HACKFORM.SCX in the Download file ) to get around the configuration frustrations that accompanied the BROWSE technique. This top-level form allows you to select a form or visual class library. It opens the file and displays the information inside it. I protected some of the fields I felt I had no business changing. The rest are open to modify to my heart's content (or until I can disable the file altogether). When you "do form HACKFORM," you'll be presented with the Open dialog, and if you're running in the same location as the source code, you'll be tempted to open one of the source code's class libraries (cBase or cCustom). Resist the temptation and instead open one of your own class libraries. One of the nicest things about this utility is that, when the table is open, you can manipulate the data in ways you've been using for years with invoices, customers, and widget tables using the BROWSE command. You can even make global replacements with Hack VCX/SCX. Jump over to Visual FoxPro and bring up the DataSession dialog box. Change the DataSession to the Hack VCX/SCX session (private datasession for the form). Type in the REPLACE logic in the Command Window: REPLACE ALL ClassLoc WITH ; "c:\devvfp5apps\common\cBaseClass" ; FOR UPPER(ClassLoc) = ; "C:\DEVVFP5APPS\COMMON\BASEOBJ" Presto -- the changes are reflected back in the form. This form presents the viewing capability in a more usable format than BROWSE, without sacrificing flexibility. It doesn't help the customer directly, but if it helps the developer spend less time getting the application to market, it ultimately helps the customer. Issues with top-level forms Here are some issues I've experienced with top-level forms that I want to pass along:

n Menu shortcut keys such as cut, copy, and paste aren't automatically available. You must use a top-level menu or
construct an interface on the form to gain this functionality. While working on the beta version, I passed along a tip to gain the functionality of menus by running the menu and then deactivating it so the features were available, but the menu wasn't visible. Build a top-level menu using the Edit menu bars from Quick Menu. Then place the following code in the Form.Init() method: DO SdiEditMenu.mpr WITH THIS, .T. DEACTIVATE MENU (THIS.Name)

n Reports called from the form -- those that run in the print preview -- run in the VFP Frame. This causes the VFP
Frame to appear when the report is run, and disappear when the report preview is shut down. This might be disconcerting to the user. If this is a problem for you, check out the Microsoft Knowledge Base for information on ways to deal with this problem. Top-level forms don't automatically include a status bar via the SET STATUSBAR ON command. You either need to make your own status bar or use an ActiveX Status Bar control. Make sure you don't have any Application.Visible = .T. settings in your code unless you want the VFP Frame to become visible. If you have an SDI form that seems to bring up the VFP frame as well, this might be the case unless you forgot the SCREEN = OFF in CONFIG.FPW. Don't forget a READ EVENT in calling a main program if you intend to make the form a standalone .EXE; otherwise the form starts and shuts down. This isn't specific to top-level forms, but it's more likely that you'll run into it while you're using top-level forms. Form icons default to the "Windows" default icon instead of the FoxPro logo. This is acceptable, but it doesn't reflect the purpose of the form.

n n n n

Conclusion Ever since FoxPro was released on the Windows platform developers have asked for the capability to build applications without displaying the main FoxPro window. They stated that their applications would be more professional and polished if they could start customized solutions with a splash screen, followed by the main application frame. Visual FoxPro 5.0 allows you to develop applications with this functionality. Enjoy! Sidebar: Top-Level Menus Top-Level Menus for using been we?ve menus standard the from different slightly they?re but menus, these to magic real no There?s frame. VFP in runs menu a like just form top-level menu forms. Add developers allow the first difference involves checking the top-level form on the menu's General Options dialog box (see Figure 3). Figure 3: General Options dialog box.

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06

Print Article

Seite 5 von 5

GenMenu generates code in the .MPR file, which includes some new code that handles the needed changes for the menu to run in a top-level form. It also has some excellent documentation on how to implement the menu. For years in FoxPro we've been running menus by running code such as this: DO MainMenu.mpr Top-level menus are run in a similar fashion from the SDI Form.Init() method: DO SDImenu.mpr WITH THIS,.T. The two parameters in this call are specific to top-level menus. The first parameter is a reference to the form. The second parameter can either be the name of the menu or a logical that tells the menu to rename the form to the name of the menu. This is used if you run multiple instances of the form. If you choose to change the form Name property via this parameter, make sure that all references to the form include THISFORM or THIS -- not a hard-coded reference to the Name property. Otherwise your code may not work. Remember to remove the menu from memory in the SDI Form.Destroy() method unless you want to reactivate it later in a new form (this is helpfully stated in the generated code). If you run the menu using the parameters in the previous example, you can place the following code in the Form.Destroy() method:

RELEASE MENU (THIS.Name)

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06