FoxTalk. GOING through the classes provided in the FoxPro. More Gems in the FFC. Doug Hennig 6.0

Transcription

1 FoxTalk Solutions for Microsoft FoxPro and Visual FoxPro Developers This is an exclusive supplement for FoxTalk subscribers. For more information about FoxTalk, call us at or visit our Web site at Extended Article More Gems in the FFC Doug Hennig 6.0 This month, we ll look at classes in three categories of the FoxPro Foundation Classes: User Controls, Text Formatting, and Output. GOING through the classes provided in the FoxPro Foundation Classes (FFC) in VFP 6 makes you feel like a kid going through a stack of a friend s baseball cards: got it, don t want it, don t want it, got it, need it. Last month, we looked at some of the classes in the FFC (see Mining for Gold in the FFC ). This month, we ll take a look at more of them, deciding which ones are actually useful and when, which need to be subclassed to improve their behavior, and which ones are duds. User Controls The User Controls subfolder of the Foundation Classes folder in the Visual FoxPro Catalog of the Component Gallery contains a variety of controls intended for use in various dialog boxes you create. (From now on, I ll just refer to the subfolder without mentioning where it can be found, since they re all in the Foundation Classes folder.) We looked at Resize Object (the _Resizable class in _CONTROLS.VCX) last month. Get File and Directory (the _Folder class in _CONTROLS.VCX) is only useful if you re building project management tools for other developers; it has controls for the name and directory of a project, and a check box indicating that the project directory structure should be created. This could be used in a New Application Wizard, for example (in fact, it s used in the VFP Application Wizard, which is probably the only reason it s included in the FFC), but it has no place in the kinds of user apps we build. MouseOver Effects (the _MouseOverFX in _UI.VCX) provides coolbar effects for controls (making the object appear raised, like the buttons in the VFP Standard and Internet Explorer toolbars). In my opinion, this class is demoware ; if you want to create toolbars with this effect, use the Microsoft Coolbar ActiveX control that comes with VFP 6. For other kinds of controls, this just looks like showing off to me. The rest of the classes in the User Controls folder are mover classes components that present the traditional two lists (one of available items and one of selected items) and buttons for moving items between the lists. Mover (the _Mover class) is the parent class for all of these classes, all of which are defined in _MOVERS.VCX. It has the following methods: InitChoices: Sets the list of available items (the left list box) to the values in the passed array. If the SortLeft property is.t., the list will be sorted. If the UseArrays property is.t. (the default), the passed array is copied to the achoices array property and the list box is based on this array; otherwise, the entries in the passed array are copied to the list using AddItem. If some items are already selected, they shouldn t be in the array passed to this method. InitSelections: Sets the list of already selected items (the right list box) to the values in the passed array. As with InitChoices, the passed array is copied to the aselections array property, and the list box is based on this array if the UseArrays property is.t. SizeToContainer: Sizes and positions all of the objects appropriately based on the container size. GetSelections: Populates the passed array with the selected items and returns the number of items. The right list has mover bars, so the user can rearrange the list; GetSelections returns them in the order they appear in the list. _Mover has label objects (Label1 and Label2) above the lists that by default have no Caption values set but can be used as headings for the lists. It also has an Updated FoxTalk Extended Article: January

2 property that contains.t. if the user added items to or removed items from the selected list. There are a couple of bugs in _Mover. Unfortunately, you have to fix these bugs right in the class rather than creating a subclass and fixing them there, because the other mover classes in _MOVERS.VCX are subclasses of _Mover. The PopList method, which populates a list box with items in a passed array, doesn t handle singly dimensioned arrays correctly. Here s the fix: LPARAMETER alistarray,olstref EXTERNAL ARRAY alistarray private ctmpliststr,i m.ctmpliststr = "" *** NEW CODE if alen(alistarray, 2) = 0 for m.i=1 to alen(alistarray) m.olstref.additem(alistarray[m.i]) endfor else *** END OF NEW CODE for m.i=1 to alen(alistarray,1) m.olstref.additem(alistarray[m.i,1]) endfor *** NEXT LINE IS NEW endif alen(alistarray, 2) = 0 The Click method of cmdremove doesn t properly sort the left list when an item is moved to it from the right list. Here s a snippet of code from this method that shows the fix: * IF this.parent.lstleft.sorted IF this.parent.sortleft =ASORT(this.parent.aChoices) ENDIF MOVER1.SCX, available in the Subscriber Downloads at and shown in Figure 1, shows how _Mover is used. It displays a list of available company names and those already selected (I just picked a few at random). The form s Init method has the following code: local lachoices[1], ; laselections[3] use (_samples + 'DATA\CUSTOMER') select COMPANY from CUSTOMER into array lachoices * Preselect a few of these and remove them from the * choices list. laselections[1] = lachoices[4] laselections[2] = lachoices[8] laselections[3] = lachoices[11] Figure 1. MOVER1.SCX demos the _Mover class. adel(lachoices, 11) adel(lachoices, 8) adel(lachoices, 4) dimension lachoices[alen(lachoices) - 3] * Now populate the mover lists, set captions for the * labels, and size it appropriately. with This.oMover.InitChoices(@laChoices).InitSelections(@laSelections).Label1.Caption = 'Available companies:'.label2.caption = 'Selected companies:'.sizetocontainer() endwith Try moving some items between the lists and rearrange the items in the right list. Click on the Results button to display whether you made any changes or not, how many companies are selected, and what their names are. Super Mover (the _SuperMover class) is a subclass of _Mover that has additional behavior: It has add all and remove all buttons (and all buttons have pictures rather than text prompts) and supports a maximum number of items that may be selected (the MaxItems property with the error message to display in the MaxMessage property). Like _Mover, it has a bug dealing with sorting items in the left list after they ve been moved from the right. The following snippet shows the fix for the Click method of cmdremoveall: *lsorted = this.parent.lstleft.sorted lsorted = this.parent.sortleft To see how _SuperMover works, right-click on the class in the Component Gallery and run the sample from the context menu that appears. Field Mover (the _FieldMover class) is a subclass of _SuperMover, Table Mover (_TableMover) is a subclass of _FieldMover, and Sort Mover (_SortMover) is a subclass of _Mover; these classes provide field mover, field mover with database and table selection, and field and index mover features. The main problem with these classes is that they use actual field names rather than their captions. As a result, your users have to know the actual names of fields rather than the English names they probably know them by. Also, there s no facility for excluding certain fields, so the user will see primary key fields even if they never see them anywhere else in the application. These problems severely limit the usefulness of these classes in anything but tools intended for other developers (these classes are used in various wizards included with VFP), which is too bad, because I can see these classes could have been useful for things like allowing the user to select which fields should appear in a grid or how a report should be sorted. Let s subclass _FieldMover to give us some new functionality: displaying field captions rather than field names and providing the ability to remove certain fields 2 FoxTalk Extended Article: January

3 from the list. SFFieldMover (in SFFFC.VCX, available in the Subscriber Downloads) overrides the GetTableData method (which reads the structure of a table and adds the fields to the list boxes). Here s a snippet from this method that s the changed code: for lni = 1 to fcount() lcfield = field(lni) lcafield = alias() + '.' + lcfield if This.IsFieldValid(lcAField) lccaption = '' if not empty(dbc()) and indbc(lcafield, 'Field') lccaption = dbgetprop(lcafield, 'Field', ; 'Caption') endif not empty(dbc())... lccaption = iif(empty(lccaption), ; proper(strtran(lcfield, '_', ' ')), lccaption) lnfields = lnfields + 1 dimension apickfields[lnfields] dimension This.aFieldList[lnFields, 2] apickfields[lnfields] = lccaption This.aFieldList[lnFields, 1] = lccaption This.aFieldList[lnFields, 2] = lcfield endif This.IsFieldValid(lcAField) next lni Since we need to keep track of both the field caption and name, I added a new afieldlist array property to the class. The preceding code gets the caption of the field from the database container (or uses a cleaned up field name if it s a free table or the caption is blank) and adds the caption to apickfields (which will later be used to populated the available fields list box) and the caption and field name to This.aFieldList. I also added an abstract method, IsFieldValid, which determines whether the field can be added to the list. This method simply returns.t. in this class, but in a subclass or instance, you can put code (typically in a CASE statement) that returns.f. for certain fields. This can be hard-coded (by comparing the passed field name to a list of field names) or data-driven (using, for example, DBCX properties to determine whether the field should be used; see my article, DBCX 2: The Quickening, in the August 1998 issue of FoxTalk for details on DBCX). I also overrode the GetSelections method, since we want to return an array of field names, not the captions. Here s the code for that method: lparameters tafields local lncount, ; lafieldlist[1], ; lni, ; lcfield, ; lnfield with This lncount =.lstright.listcount if lncount > 0 acopy(.afieldlist, lafieldlist) dimension tafields[lncount] for lni = 1 to lncount lcfield =.lstright.list[lni] lnfield =.AColScan(@laFieldList, lcfield, 1) tafields[lni] = iif(lnfield = 0, '', ;.afieldlist[asubscript(.afieldlist, lnfield, ; 1), 2]) next lni endif lncount > 0 endwith return lncount MOVER2.SCX, shown in Figure 2, shows how SFFieldMover is used; it displays fields from the CUSTOMER sample table that comes with VFP. The IsFieldValid method of the SFFieldMover instance prevents the CUST_ID and MAXORDAMT fields from being available. The code in the Init method of this sample form is very simple: open database (_samples + 'DATA\TESTDATA') use CUSTOMER This.oFieldMover.InitData() This.oFieldMover.SizeToContainer() Text Formatting The Text Formatting subfolder of the Component Gallery contains several controls, all of which are contained in _FORMAT.VCX, for formatting text. Font Combobox (class _cbofontname) contains a list of fonts installed on the system (using VFP s AFONT() function) and Fontsize Combobox (_cbofontsize) contains font sizes for a specific font. RTF Controls (_RTFControls) and Format Toolbar (_tbrediting) are both toolbars consisting of controls for text formatting, but _tbrediting is the more feature-rich of the two. It has _cbofontname and _cbofontsize controls, command buttons for bold, italics, and underline settings, and a combo box for setting foreground and background colors. The toolbar has an nappliesto property that contains 1 if the settings apply to the current control in the active form, 2 if they apply to all text box and edit box objects in the form, or 3 if they apply to all controls in the form. The InteractiveChange event of each control adjusts the appropriate property of the appropriate controls (based on nappliesto) in the active form. The _cbofontname object also adjusts the _cbofontsize object so it displays sizes for the selected font. Although a sample is registered for these classes, it doesn t show how changing nappliesto affects the formatting, so I whipped up a quick and dirty demo, EDITING.SCX (shown in Figure 3), to do that. Type some text into the text box and edit box, then use the toolbar to change the formatting. Choose a different option in the option group, and notice that formatting then applies to different controls (even the option buttons). Notice that the toolbar reflects the settings of the current control; this Figure 2. MOVER2.SCX demos the SFFieldMover class. FoxTalk Extended Article: January

4 is done by refreshing the toolbar in the GotFocus method of each control. I haven t used the toolbar for an actual project, but I have used the _cbofontname and _cbofontsize classes in a preferences form where the user could choose the font and size for grids in an application. These settings were stored in the Registry (see last month s column for the SFRegistry class that handles reading from and writing to the Registry) and restored in the Init method of the grid class. Output As you might guess from its name, the Output subfolder of the Component Gallery contains controls related to outputting information. These classes are all located in _REPORTS.VCX. Text Preview (the _ShowText class) displays the contents of a text file; I think this is one of those yes, you can do this in VFP, but why would you kind of things, since Notepad works just fine for me (although if you really need to display a text file within VFP with more control than MODIFY FILE, this class would do the trick). Output Control (_OutputChoices) is a container class with options for output type (report, export file, HTML, and so forth), output options (which printer, export file type, and so on), and output filename. Output Dialog (_OutputDialog) is a form class with an _OutputChoices control plus options for which records to output, and which report and data sources to use. If you can live with the behavior and appearance of these classes, they d likely be useful to you. Unfortunately, the user interface isn t something I d want to give to a typical user, so I m going to bypass these classes. Output Object (_Output) is the gem in this bunch. This class has properties and methods for outputting data in a variety of ways: printing or previewing a report, printing to a text file, outputting to HTML, displaying a read-only browse window, exporting to any export file type supported by VFP, and so forth. _Output is actually a container class that includes a _WindowHandler object (also from the FFC) to manage output windows; we might take a look at closer look at this class in a future column. Let s take a look at the more important properties and methods of _Output. The cdestination property contains the type of output the class produces. The expected values for this property are PRINTREPORT (prints the report file named in the creport property), PRINTLIST (does the equivalent of LIST TO PRINT), SCREEN (previews the creport report, browses the table, or outputs and displays a text file from either the report or LIST TO FILE), TEXTFILE (prints the creport report using REPORT FORM TO FILE ASCII), PRINTFILE (prints the creport report using REPORT FORM TO FILE), EXPORT (exports to any export file type supported by VFP), and HTMLFILE (creates and optionally displays an HTML file using Figure 3. EDITING.SCX demos the _tbrediting class. GENHTML.PRG). The assign method for this property calls the SetDestinations method (which is also called from Init); this method populates the adestinations array property with the preceding list of choices in the second column and the display version of these choices in the first column. This array can thus be used as the RowSource for a combo box (set its ControlSource to cdestination and its BoundColumn to 2), allowing the user to choose the output destination. If you don t like the text displayed to the user, you can edit the constants defined in _REPORTS.H, the include file for this class. The calias property is the data source for output. Its assign method also calls the SetDestinations method, because the list of available destinations depends on whether calias is filled in or not. For example, if calias is empty, PRINTREPORT is still available (because the DataEnvironment for the report might contain the tables required in the report), but PRINTLIST isn t. The creport property contains the name of an FRX file to use for output. As with calias, its assign method calls SetDestinations (if creport is empty, for example, PRINTREPORT isn t available, but PRINTLIST is). The coption property contains the option for the desired destination. Here are the expected values: If cdestination is SCREEN, coption can be GRAPHICAL (perform a REPORT FORM PREVIEW), ASCII (perform a REPORT FORM TO FILE and display the text file), BROWSE (browse the table), and LIST (display the text file created with LIST TO FILE), although not all of these options are always available (for example, if creport is empty, GRAPHICAL and ASCII obviously don t apply). If cdestination is PRINTREPORT, PRINTLIST, or PRINTFILE, the choices are WINDEFAULT (use the Windows default printer), VFPDEFAULT (use the VFP default printer), or SETVFPDEFAULT (display a print dialog box and set the selected printer to the VFP default). 4 FoxTalk Extended Article: January

5 If cdestination is EXPORT, coption is the desired file type (for example, DBF for table, XLS for Excel, or SDF for an ASCII file with fixed length fields). If cdestination is HTMLFILE, coption can be FILEONLY (generate the HTML file but don t display it), VIEWSOURCE (generate the HTML file and display the source), or WEBVIEW (generate the HTML file and display it in a browser). If cdestination is TEXTFILE, coption is ignored. Like adestinations, the aoptions array property is filled with the appropriate range of values (based on cdestination) by the SetOptions method. The first column of the array is the display version; and the second column is the option. This array can be used as the RowSource for a combo box (set its ControlSource to coption and its BoundColumn to 2) so the user can choose from the options applicable for the selected destination (call the SetOptions method in the InteractiveChange method of the destination combo box, and then requery the options combo box so the user can only choose from appropriate values). The cfieldlist property contains a comma-delimited list of fields for options other than those based on a report; if this property is empty, all fields are output, even calculated fields defined with SET FIELDS. If the laddsourcenametodropdown property is.t. (the default), _Output adds the contents of creport, calias, or both (depending on whether they re filled in or not) to the display values in adestinations. I doubt the user will want to see this, so I d set the property to.f. cscope contains the scope clauses used for output. If this is empty, all records are output; otherwise, it should contain a value scope expression ( REST, WHILE <expression>, FOR <expression>, and so forth). cdisplayfontname contains the font to use for browse or text file viewing windows; the default is Courier New. ctextfile is the name of the text or export file to create; if it s empty, a unique filename (based on SYS(2015)) is assigned. chtmlclass is the class GENHTML.PRG should use for the instantiated HTML object; if this is left blank, GENHTML will use the appropriate class for the type of source it s working with. chtmlstyleid specifies a style to apply to the HTML file if it s created from the table (that is, creport is empty). It should be empty or the ID value from the appropriate record in GENHTML.DBF (in the VFP home directory). The Output method does all the work of performing the output based on the calias, creport, cdestination, and coption properties. It calls the appropriate method based on how cdestination is set; for example, OutputToScreen is used when cdestination contains SCREEN. I subclassed _Output into SFOutput (in SFFFC.VCX). I didn t change a lot; I just set laddsourcenametodropdown to.f. (as I mentioned earlier) and made the SetDestinations method call the SetOptions method because changing something (such as creport) that affects the list of destinations also affects the list of options. Okay, that s a lot of background detail; let s put this sucker to work. The sample available for this and other classes in the Output folder is okay, but it doesn t give you much opportunity to try out some of the options, so I created a simple form (OUTPUT.SCX) you can use for this. This form will demonstrate output against the CUSTOMER sample table that comes with VFP. It has an SFOutput object, two combo boxes (one for destination and one for options, as I described earlier), a check box that allows you to determine whether a report file is used or not (the Init of the form creates a simple report file), and a command button that just calls the Output method of the SFOutput object. Run the form, then set the destination and notice the choice of options available. Uncheck Use report and see how the list of destinations and options change. To see how different HTML styles work, uncheck Use report (so the HTML file will be produced from the table) and set destination to HTML file and option to View output in Web browser, then click on the Output button to see the default style. To change to a different style, enter the following in the Command window, then click on the Output button again: _screen.activeform.ooutput.chtmlstyleid = "<style>" For example, try DesertCalmStyle or Graffiti (browse the GENHTML table to see what choices are available). To see how cscope works, try the following: _screen.activeform.ooutput.cscope = ; 'for COUNTRY = "Germany"' Of course, you don t have to use a dialog box with combo boxes based on adestinations and aoptions (for example, you might not want to provide all options to your users); you simply have to set cdestination and coption to appropriate values before calling the Output method. Although there s nothing in the class you couldn t do in code yourself, you ll find this class very easy to use for producing output, especially HTML files, in your applications. Conclusion We looked at the classes in the User Controls, Text Formatting, and Output folders in the Component Gallery. In my opinion, some of the classes are demoware, but others are very useful, especially with a bit of tweaking in subclasses. Of course, beauty is in the eye of FoxTalk Extended Article: January

6 the beholder, so I suggest you examine these classes and decide which ones you ll want to use yourself. 01DHENSC.ZIP at Doug Hennig is a partner with Stonefield Systems Group Inc. in Regina, Saskatchewan, Canada. He is the author of Stonefield s add-on tools for FoxPro developers, including Stonefield Database Toolkit and Stonefield Query. He is also the author of The Visual FoxPro Data Dictionary in Pinnacle Publishing s The Pros Talk Visual FoxPro series. Doug has spoken at the 1997 and 1998 Microsoft FoxPro Developers Conferences (DevCon) as well as user groups and regional conferences all over North America. He is a Microsoft Most Valuable Professional (MVP) @compuserve.com, dhennig@stonefield.com. 6 FoxTalk Extended Article: January