Microsoft Visual FoxPro 6.0 now supports OLE drag-and-drop, which allows you to move data between Visual FoxPro and other applications, and within Visual FoxPro applications.
Visual FoxPro 6.0 also makes it easy to create applications for use with the Internet and other Windows-based applications such as Microsoft Excel and Microsoft Visual Basic. Visual FoxPro 6.0 lets you create Active Documents that can be hosted by Active Document hosts such as Internet browsers.
Visual FoxPro 6.0 features improved Automation servers to work better with the Internet, Microsoft Transaction Server, and the Active Desktop.
This chapter covers:
Visual FoxPro now supports OLE drag-and-drop, a powerful and useful tool that allows you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Windows Explorer, Microsoft Word and Excel, and so on). In a distributed Visual FoxPro application, you can move data between controls in the application, or between controls and other Window applications that support OLE drag-and-drop.
Note that previous versions of Visual FoxPro supported a programmatic drag-and-drop feature for controls, allowing you to move controls on a form. This form of drag and drop is still supported in Visual FoxPro 6.0. However, if you choose to implement drag and drop support in your applications, you should exclusively use either programmatic drag and drop for controls or OLE drag-and-drop – don't mix the two types of drag and drop support.
Understanding some of the basics of OLE drag-and-drop applications makes it easier to take full advantage of their features.
The mouse is used to drag and drop data between applications and controls. For example, you can select a set of files in the Windows Explorer. You can then press and hold the mouse button down while dragging the files, then release the mouse button to drop them onto the Visual FoxPro Project Manager, or you can select text in a Word document and drop the text into a text box on a Visual FoxPro form. During the OLE drag-and-drop operation, the mouse cursor changes to indicate that an OLE drag-and-drop operation is in effect.
The application or control from which data is moved is called the drag source.
The following table lists the properties, events, and methods available for an OLE drag source.
| Property, Event, or Method | Description |
| OLECompleteDrag Event | Occurs when data is dropped on the drop target or the OLE drag-and-drop operation is canceled. |
| OLEDrag Method | Starts an OLE drag-and-drop operation. |
| OLEDragPicture Property | Specifies the picture displayed under the mouse pointer during an OLE drag-and-drop operation. You can specify a picture file of type .bmp, .dib, .jpg, .gif, .ani, .cur, and .ico. |
| OLEDragMode Property | Specifies how a drag source manages OLE drag operations. |
| OLEGiveFeedBack Event | Occurs after every OLEDragOver event. Allows the drag source to specify the type of OLE drag-and-drop operation and the visual feedback. |
| OLESetData Event | Occurs when a drop target calls the GetData method and there is no data in a specified format on the OLE drag-and-drop DataObject. |
| OLEStartDrag Event | Occurs when the OLEDrag method is called. |
The application or control to which the data is moved is called the drop target.
The following table lists the properties, events, and methods available for an OLE drop target.
| Property or Event | Description |
| OLEDragDrop Event | Occurs when data is dropped on a drop target and the drop target's OLEDropMode property is set to 1 – Enabled. |
| OLEDragOver Event | Occurs when data is dragged over a drop target and the drop target's OLEDropMode property is set to 1 – Enabled. |
| OLEDropEffects Property | Specifies the type of drop operations an OLE drop target supports. |
| OLEDropHasData Property | Specifies how a drop operation is managed. |
| OLEDropMode Property | Specifies how a drop target manages OLE drop operations. |
To perform a drag-and-drop operation to move data using the default (left) mouse button, select the data you want to move in the drag source. After selecting the data, press and hold down the mouse button as you move the mouse pointer over the drop target. Release the mouse button to drop the data onto the drop target. During the OLE drag-and-drop operation, the mouse cursor changes to indicate that an OLE drag-and-drop operation is in effect.
You can also click the non-default (right) mouse button on the data in a drag source and drag it to a drop target. Depending on the drop target, a context menu may be displayed when you drop the data on the drop target. The context menu contains a set of options that let you choose how the data is processed by the drop target.
You can also copy data from a drag source and paste it in a drop target. Press the Ctrl key as you click the mouse on the data selected in the drag source. The mouse cursor displays a plus sign (+) while the mouse is dragged to indicate a Copy operation is in effect.
You can only move or copy data from a drag source that supports OLE drag-and-drop, and the drop target must also support OLE drag-and-drop. Note that while a drop target may support OLE drag-and-drop, the drop target doesn't have to accept the data you attempt to drop on it. For example, the data you're moving or copying may be in a format the drop target doesn't support. During a drag-and-drop operation, the mouse cursor changes to a No Drop symbol (a slashed circle) to indicate the mouse is positioned over an area of an application or control where the data cannot be dropped.
To cancel the OLE drag-and-drop operation, press ESC during the operation.
Design time support for OLE drag-and-drop in Visual FoxPro makes developing applications even faster than previous versions. OLE drag-and-drop makes it easy to drop files into the Project Manager and the Visual FoxPro designers from the Windows Explorer. Text can be easily moved or copied from other applications to the Command Window, the Visual FoxPro text editors, and the Properties Window.
The following table lists the Visual FoxPro design time features that support OLE drag-and-drop with a description of the support.
| Interface item | Description |
| Command Window | Drop target for files, drag source and drop target for text. If a file created in Visual FoxPro is dropped on the Command window, the file is opened with the appropriate Visual FoxPro command. For example, if a database is dropped on the Command window, Visual FoxPro issues the OPEN DATABASE and MODIFY DATABASE commands to open the file for modification. If a table is dropped on the Command window, the table is opened with the USE … AGAIN and BROWSE commands. If SET EXCLUSIVE is ON, the table is opened for exclusive use. If SET EXCLUSIVE is OFF, the table is opened for shared use. Other Visual FoxPro files are opened with the appropriate MODIFY command — forms are opened with MODIFY FORM, queries are opened with MODIFY QUERY, text and header (.H) files are opened with MODIFY FILE, and so on. If a file that has been created in another application is dropped on the Command window, the file is opened in the application with which it is associated. For example, dropping a Microsoft Excel spreadsheet on the Command window starts Excel and opens the spreadsheet. |
| Project Manager | Drop target for files. Files are added to the appropriate Project Manager categories, based on their file extensions. If a file with an extension Visual FoxPro does not recognize is dropped on the Project Manager, the file is added to the Other category. If a table contained in a database is dropped on the Project Manager, the database is added to the Databases category of the Data item and is marked as Excluded. If a free table is dropped on the Project Manager, the table is added to the Free Tables category of the Data item and is marked as Excluded. If a database is dropped on the Project Manager, the database is added to the Databases category of the Data item and is marked as Excluded. While OLE drag-and-drop makes it easy to add files to the Project Manager, remember that the Project Manager automatically adds any referenced files to the project when you build the project. For example, if a program you add to the project executes a second program, the second program is automatically added to the project when the project is built. It isn't necessary to manually add the second program to the project. |
| Text Editors |
Drag source and drop target for text. Text editors include editing windows opened with MODIFY COMMAND, MODIFY FILE, and MODIFY MEMO, the Command window, snippet editing windows in the Form, Class, Menu, and Data Environment Designers, and the Stored Procedure editor in the Database Designer. |
| Debugger | Drag source and drop target for text. The Watch window text box and Name list are drag sources and drop targets for text. The Trace window and the Debug Output window are drag sources for text. |
| Database Designer | Drop target for files. Dropping a table onto the Database Designer adds the table to the current database. |
| Class Designer | Drop target for text and files. By default, dropping text on a container object in the Class Designer creates a label with the text as the value of its Caption property. You can change the default control created when text is dropped on the Form Designer in the Field Mapping Tab of the Options Dialog Box. If you drop text onto a non-container control (a CheckBox, CommandButton, Header, Label, or OptionButton control), the control's Caption property is set to the text. Dropping a graphics file (.ani, .bmp, .cur, .gif, .ico, or .jpg) onto the Class Designer creates an Image control with the Picture property set to the name of the graphics file. |
| Data Environment Designer | Drop target for files. Dropping a table onto the Data Environment Designer adds the table to the data environment. Dropping a database onto the Data Environment Designer displays the Add Table or View dialog, allowing you to add a table or view to the data environment. |
| Query Designer | Drop target for files. Dropping a table onto the Query Designer adds the table to the query. Dropping a database onto the Query Designer displays the Add Table or View dialog, allowing you to add a table or view to the query. |
| View Designer | Drop target for files. Dropping a table onto the View Designer adds the table to the view. Dropping a database onto the View Designer displays the Add Table or View dialog, allowing you to add a table or view to the view. |
| Properties window | Drop target for text. You can drop text onto the text box that appears at the top of the Properties window when a design time property is selected. |
| Component Gallery | Drag source and drop target for files. You can drag objects out of the Component Gallery and drop them onto the Form Designer. You can also drag files out of the Component Gallery and drop them onto the Project Manager. Files can be dropped on the Component Gallery. |
OLE drag-and-drop support is available at run time for Visual FoxPro controls and the text editor. The controls and the text editor support OLE drag-and-drop interactively at run time, and the controls provide programmatic support at run time. The DataObject object provides programmatic OLE drag-and-drop support for the controls.
Two modes of OLE drag-and-drop are available for Visual FoxPro controls: intrinsic mode and manual mode. In intrinsic mode, Visual FoxPro intrinsically handles an OLE drag-and-drop operation. In manual mode, OLE drag-and-drop operations are handled programmatically. The events that occur are determined by the OLE drag-and-drop mode. For more information, see the section, "Intrinsic and Manual OLE drag-and-drop Modes."
Previous versions of Visual FoxPro supported programmatic drag-and-drop for controls, allowing you to move controls on a form. This form of drag and drop is still supported. If you use the default settings for the OLEDragMode and OLEDropMode properties, your existing applications will run as before without any changes.
The DataObject object is a container for data being transferred from an OLE drag source to an OLE drop target, and exists only for the duration of an OLE drag-and-drop operation. The DataObject object cannot be created programmatically and references to it become invalid once the OLE drag-and-drop operation is completed. The DataObject is passed as the oDataObject parameter in the OLEStartDrag, OLEDragOver, OLEDragDrop, and OLESetData events.
The DataObject can store multiple sets of data, each in a different format. The existence of a specific format in the DataObject can be determined with the GetFormat method. See the GetFormat Method for a listing of the formats supported by the DataObject.
The DataObject object has methods that allow you to programmatically manipulate the data being dragged and dropped. The following table lists the methods available at run time for the DataObject.
| Method | Description |
| ClearData | Clears all data and data formats from the OLE drag-and-drop DataObject object. |
| GetData | Retrieves data from the OLE drag-and-drop DataObject object. |
| GetFormat | Determines if data in a specified format is available on the OLE drag-and-drop DataObject. |
| SetData | Places data and its format on the OLE drag-and-drop DataObject. |
| SetFormat | Places a data format without data on the OLE drag-and-drop DataObject. |
Visual FoxPro supports two OLE drag-and-drop modes for controls: intrinsic and manual. In intrinsic mode, OLE drag-and-drop operations are handled by Visual FoxPro. In manual mode, OLE drag-and-drop operations are under programmatic control.
Intrinsic OLE drag-and-drop mode can be implemented in an application to provide standard OLE drag-and-drop support without any additional programming.
To implement intrinsic OLE drag-and-drop support for a control
For intrinsic OLE drag-and-drop operations, Visual FoxPro determines if the drop target supports the format of the data being dropped on it; if the drop target supports the format, the drop occurs, otherwise the drop is not allowed.
The following table lists the Visual FoxPro controls and the data formats they support as drag sources in intrinsic mode. Note that CF_TEXT is text, such as text you would enter in a text box, and CFSTR_VFPSOURCEOBJECT is an object type reference to a Visual FoxPro control or object. For the controls below that support the CF_TEXT data format, you can drag text from the text portion of the control.
Drag Source Data Formats
Control |
Data Format (defined in Foxpro.h) |
| Container, Image, Line, PageFrame, and Shape | CFSTR_VFPSOURCEOBJECT |
| CommandButton and Label | CFSTR_VFPSOURCEOBJECT and CF_TEXT |
| CheckBox, ComboBox, EditBox, ListBox, Spinner, and TextBox | CFSTR_VFPSOURCEOBJECT, CF_TEXT, and CFSTR_OLEVARIANT |
The Visual FoxPro controls and data formats they support as drop targets in intrinsic mode are listed in the following table. For the controls listed in this table, you can drop text onto the text portion of the control. The text is inserted at the insertion point.
Drop Target Data Formats
| Control | Data Format |
| EditBox and ComboBox (When the ComboBox Style property is set to 0 - Dropdown Combo) | CF_TEXT |
| Spinner and TextBox | CFSTR_OLEVARIANT |
There may be cases where you'd like to control the type of data that can be dropped on a drop target, or provide additional functionality for a drag-and-drop operation. For example, you can convert data to a format supported by the drop target, or you can display a dialog that asks the user if they're sure they want to drop the data on the drop target. In cases such as these, override the intrinsic OLE drag-and-drop support to provide greater control over drag-and-drop operations.
To implement manual OLE drag-and-drop support for a control, override the drag or drop events or methods you want to control to by writing your own event or method code. Include the NODEFAULT keyword in the event or method code to override the intrinsic Visual FoxPro drag-and-drop behavior.
Backward compatibility (no OLE drag support) is provided for existing applications when OLEDragMode is set to 0 (the default) and you do not include additional OLE drag-and-drop coding.
Visual FoxPro 6.0 allows you to create Active Documents. Active Documents enable you to view non-HTML documents in a Web browser host such as Microsoft Internet Explorer. Active Document technology allows you to view multiple types of documents from multiple sources within a single Active Document host.
An Active Document is a specific type of OLE embeddable document. It displays in the entire client area of an Active Document host and does menu merging with the host. The Active Document is full-frame and always in-place active.
The following are some of the features that Active Documents provide:
Visual FoxPro Active Documents are easy to create. A Visual FoxPro Active Document, like any other Visual FoxPro application, can manipulate data, run forms, reports, and labels, instantiate classes, and run code.
A Visual FoxPro Active Document is an application (.app) created from a Visual FoxPro project. Earlier versions of Visual FoxPro allowed you to create applications, so you may already be familiar with creating applications. For more information about creating applications, see Chapter 13, Compiling an Application, in the Programmer's Guide.
Any application can be run in Internet Explorer. However, only applications based on the ActiveDoc base class, described below, support the properties, events, and methods that provide communication with the Active Document host.
Visual FoxPro Active Documents differ slightly from other applications (.app). The most notable difference is that the “main file” for an Active Document must be set to a class based on the ActiveDoc base class. Other types of applications require that the main file be a program or a form.
A class based on the ActiveDoc base class is created with the Class Designer and serves as the basis for all Visual FoxPro Active Documents. The ActiveDoc base class provides properties, events, and methods for an Active Document, and provides communication with the Active Document host. For example, the ContainerRelease event occurs when an Active Document is released by its host. You can place code in the ContainerRelease event to close files, complete transactions, and perform other clean up duties before the Active Document is released.
To set the main file to a class based on the ActiveDoc base class
When a Visual FoxPro Active Document is run in Internet Explorer, an ActiveDoc object is created from the ActiveDoc base class. The ActiveDoc object responds to events and method calls for the ActiveDoc base class.
The following tables list the properties, events, and methods supported by the ActiveDoc object.
Properties
| BaseClass | Caption | Class |
| ClassLibrary | Comment | ContainerReleaseType |
| Name | Parent | ParentClass |
| Tag |
Events
| CommandTargetExec | CommandTargetQuery | ContainerRelease |
| Destroy | Error | HideDoc |
| Init | Run | ShowDoc |
Methods
| AddProperty | ReadExpression | ReadMethod |
| ResetToDefault | SaveAsClass | WriteExpression |
When an Active Document application is opened in Internet Explorer, the Active Document runs and the Active Document’s Init event occurs. Then the Active Document’s ShowDoc event occurs. When Internet Explorer successfully hosts the Active Document, the Active Document’s Run event occurs. In general, the Active Document program code should be placed in this event. Typically, the Run event contains code that executes your menu code, executes the main form in the application, and contains READ EVENTS to start event processing, just like a standard Visual FoxPro application.
You can put setup code in your Active Document’s Init event, but if the code takes too long to execute, the Active Document container might generate a time out error. If you do put setup code in the Init event, it should not require user interaction or create a user interface.
The HideDoc event occurs if you navigate from an Active Document, and the ShowDoc event occurs when you navigate back to the Active Document.
If Internet Explorer is closed when the Active Document is hosted, the HideDoc event occurs, and then the ContainerRelease Event occurs. The ContainerRelease event also occurs if the Active Document falls out of the Internet Explorer 3.0 cache.
When the ContainerRelease event occurs, the program code in the event can do the following:
Note The CommandTargetExec event occurs if Internet Explorer 4.0 is about to close the Active Document or navigate from the Active Document. In this case, the CommandTargetExec event nCommandID parameter is set to 37, and you can set the eArgOut parameter to false (.F.) to prevent the Active Document from being closed by Internet Explorer. Internet Explorer 3.0 doesn’t support the CommandTargetExec event.
Two new functions, GETHOST( ) and ISHOSTED( ), have been added to Visual FoxPro to provide information about an Active Document’s host. GETHOST( ) returns an object reference to an Active Document’s host. ISHOSTED( ) returns a logical value indicating if an Active Document is hosted.
The user interface in a Visual FoxPro Active Document is defined by its program code. In general, a Visual FoxPro form should be displayed as the initial user interface. The following form properties, events, and methods have been added to Visual FoxPro to allow forms to work well in Active Documents.
| Properties | ||
| AlwaysOnBottom | ContinuousScroll | HscrollSmallChange |
| Scrollbars | TitleBar | ViewPortHeight |
| ViewPortLeft | ViewPortTop | ViewPortWidth |
| VScrollSmallChange |
| Events | ||
| Scrolled |
| Methods | ||
| SetViewPort |
Forms in an Active Document are displayed in the client area provided by Internet Explorer. To make a form display entirely within the Internet Explorer client area, set the following form properties to these values:
BorderStyle = 0 (No Border)
TitleBar = 0 (Off)
WindowState = 2 (Maximized)
Also, if scrollbars should be displayed when the Internet Explorers client area is smaller than the Active Document viewport (the area determined by a rectangle that encloses all the controls on the form), the Scrollbars property should be set to the following value:
ScrollBars = 3 (Both horizontal and vertical scrollbars)
If menu code is run in a Visual FoxPro Active Document, the menus are merged with the Internet Explorer menus, following specific menu merging rules. Once the Active Document menus are merged with those of Internet Explorer, the Active Document menus appear as if they would in a traditional Visual FoxPro application.
In Visual FoxPro 6.0 and earlier versions, you can specify menu negotiation behavior for menus when OLE visual editing occurs for an ActiveX control contained in a Visual FoxPro form. In Visual FoxPro 6.0, menu negotiation has been enhanced to provide control over where menus in an Active Document appear in Internet Explorer.
When an Active Document is open in Internet Explorer, it shares menu space Internet Explorer and menus are merged together. Menus from Internet Explorer are merged with menus from the Active Document. The merged menus fall into six groups, and each group is owned by Internet Explorer, the Active Document, or both.
| Group | Owner |
| File Group | Internet Explorer |
| EditGroup | Active Document |
| Container Group | Internet Explorer |
| Object Group | Active Document |
| Window Group | Internet Explorer |
| Help Group | Active Document or Internet Explorer |
The Active Document shares its Help menu with Internet Explorer. If Internet Explorer has a help menu, the Active Document can add its help menu to the end of Internet Explorer’s help menu.
The DEFINE PAD NEGOTIATE clause has been enhanced to allow you specify how menu negotiation occurs for menus in an Active Document. A new second option, cObjectPosition, specifies the location of a menu title in the Internet Explorer menu bar.
See DEFINE PAD in the Language Reference for more information.
The Prompt Options dialog box in the Menu designer has been enhanced, allowing you to specify menu negotiation for menus created in the Menu Designer and included in Active Documents. An Object drop-down has been added; this drop-down specifies how the menu title is negotiated when a Visual FoxPro Active Document is hosted in Internet Explorer.
The menu negotiation information is stored in the Location field of a menu’s .mnx file. The following table lists the values in this field and the type of menu negotiation for each value. See DEFINE PAD for more information about cContainerPosition and cObjectPosition.
| Value | cContainerPosition | cObjectPosition |
| 0 | None | None |
| 1 | Left | None |
| 2 | Middle | None |
| 3 | Right | None |
| 4 | None | Left |
| 5 | Left | Left |
| 6 | Middle | Left |
| 7 | Right | Left |
| 8 | None | Middle |
| 9 | Left | Middle |
| 10 | Middle | Middle |
| 11 | Right | Middle |
| 12 | None | Right |
| 13 | Left | Right |
| 14 | Middle | Right |
| 15 | Right | Right |
Note that in Visual FoxPro 6.0 the Location field size was increased from 1 digit to 2 digits. This is the only change made in Visual FoxPro 6.0 to the structures of tables, including database (.dbc), form (.scx), label (.lbx), project (.pjx), report (.frx), and visual class library (.vcx) tables.
Two Active Document events, CommandTargetExec and CommandTargetQuery, allow you to manage Internet Explorer menu selections (and other Internet Explorer events) from an Active Document. The CommandTargetExec event occurs when Internet Explorer notifies an Active Document of a command (including a menu command) to be executed. The CommandTargetQuery event occurs when Internet Explorer updates its user interface. See CommandTargetExec Event and CommandTargetQuery Event in the Language Reference for more information about each event.
Visual FoxPro Active Documents require Vfp6.exe and Vfp6run.exe, or Vfp6run.exe, Vfp6r.dll, and Vfp6renu.dll (enu denotes the English version) to run. These files must be installed and registered on the computer on which Internet Explorer is installed. When Visual FoxPro is installed, Vfp6.exe is installed in the Visual FoxPro directory, and the remaining files are installed in the Windows 95 Windows\System directory or the Windows NT WinNT\System32 directories.
The Visual FoxPro Tools menu contains a Run Active Document command that you can choose to display the Run Active Document dialog box. In this dialog you can specify how an Active Document is run. The following options are available:
| Option | Description |
| In Browser (Default) | The Active Document is run in Internet Explorer using the Visual FoxPro runtime. |
| Stand Alone | The Active Document is run as a stand-alone application with the Visual FoxPro runtime. |
| In Browser (Debugging) | The Active Document is run in Internet Explorer using the Visual FoxPro executable (Vfp6.exe). Debugging capabilities, the Command window, and all features of the Visual FoxPro development environment are available. |
| Stand Alone (Debugging) | The Active Document is run as a stand alone application with the Visual FoxPro executable (Vfp6.exe), providing debugging capabilities, the Command window, and all features of the Visual FoxPro development environment. Choosing this option is identical to issuing DO <Active Doc Name> in the Command window. |
You can also run an Active Document by opening the Active Document from the Open File dialog box in Internet Explorer, or by navigating to the Active Document from another Web page with a hyperlink to the Active Document.
From Visual FoxPro you can run an Active Document by double-clicking the Active Document icon in the Windows Explorer. You can also run an Active Document from a Visual FoxPro runtime application. The Visual FoxPro runtime consists of two files, Vfp6run.exe and Vfp6r.dll. Both must be installed and registered to run Active Documents. The runtime can also be used to run other Visual FoxPro distributable files such as compiled Visual FoxPro programs (.fxp files).
Vfp6run.exe, once registered, can be used to run Active Documents (and other Visual FoxPro distributable files) directly.
Syntax for Vfp6run.exe
VFP6RUN [/embedding] [/regserver] [/unregserver] [/security]
[/s] [/version] [FileName]
Arguments
/embedding
Loads Vfp6run.exe as an active document server. In this mode, Vfp6run.exe is registered as a COM server capable of creating a Visual FoxPro Active Document object ("Visual.FoxPro.Application.6"). Without this argument, Vfp6run.exe doesn’t act as a COM server.
/regserver
Registers Vfp6run.exe.
/unregserver
Unregisters Vfp6run.exe.
/security
Displays the Application Security Settings dialog box, allowing you to specify the security settings for Active Documents and other application (.app) files. For more information, see the next section, "Active Document Security."
/s
Silent. Specifies that an error is generated if Vfp6run.exe is unable to load the Vfp6r.dll runtime component.
/version
Displays Vfp6run.exe and the Vfp6r.dll version information.
FileName
Specifies the Visual FoxPro file to run.
Vfp6run.exe requires that the runtime support dynamic link library Vfp6r.dll be installed and registered. To register Vfp6r.dll, run Regsvr32 with the name of the runtime:
Regsvr32 Vfp6r.dll
The /security option for the Vfp6run.exe Visual FoxPro runtime allows you to set security levels for Active Documents and other application (.app) files. Executing Vfp6run.exe /security displays the Application Security Settings dialog box where you can set security levels for Active Documents and other .app files.
The following options are available in the Application Security Settings dialog box:
Choose this application mode setting to specify a security level for an Active Document or application (.app) that is run from an Active Document container such as Internet Explorer.
Choose this application mode setting to specify a security level for an Active Document or application (.app) that is run from the Window Explorer by double-clicking its icon, or is run with the Visual FoxPro Vfp6run.exe runtime.
Choose this setting to prevent an Active Document or application (.app) from being run.
Choose this setting to display a warning before an Active Document or application (.app) is run. Medium is the default setting for non-hosted Active Documents and applications.
Choose this setting to run an Active Document or application (.app) without displaying a warning. Low is the default setting for hosted Active Documents and applications.
Restores the default security level for the currently selected application mode (hosted or non-hosted).
Saves the settings you choose in the dialog box.
To increase performance, Internet Explorer 3.0 caches the last four pages visited in memory. This means that an Active Document can fall out of the Internet Explorer 3.0 cache, causing the ContainerRelease event to occur. Internet Explorer 4.0 does not have a page cache, so the ContainerRelease event occurs as soon as you navigate from an Active Document.
The Visual FoxPro Solutions Sample application includes a sample named “Create Active Documents for the web” that demonstrates many of the Active Document features.
To run the Solutions Sample application
DO (HOME(2) + 'solution\solution')
– Or –
To run the “Create Active Documents for the web” sample
The “Create Active Documents for the web” sample allows you to open a project that contains all of the files necessary to create an Active Document from the project. When the project is open, you can examine the code in the Actdoc class to see how Active Document events are managed and how forms are run. Note that Actdoc, a class based on the ActiveDoc base class, is set as the main file in the project. An Active Document must have a class based on the ActiveDoc base class as its main file.
You can also create build an Active Document from the project by choosing Build in the Project Manager. After the Active Document is built, choose Run Active Document from the Tools menu to run the Active Document.
This topic describes improvements made to Visual FoxPro 6.0 Automation servers, and includes discussions of how Visual FoxPro Automation servers can work with products and technologies such as Microsoft Transaction Server and Microsoft Visual Basic.
Visual FoxPro allows you to create Automation servers. An Automation server is a component application that exposes functionality that can be used and reused by other applications through Automation. For example, using Visual FoxPro you can create an Automation server that displays reusable forms (in an out-of-process .exe), or packages a complex routine into a simple component that other programmers can use. In addition, you could create one or more classes to handle enterprise-wide business rules. A client application that uses the business rule objects would pass input parameters in a method call, and the Automation server might then do a great deal of work, retrieving or storing data from various sources and performing complex calculations, before returning the answer.
In Visual FoxPro, you can create either an out-of-process or an in-process Automation server. An out-of-process component is an executable (.exe) file that runs in its own process. Communication between a client application and an out-of-process server is therefore called cross-process communication. An in-process component is a dynamic-link library (.dll) file that runs in the same process address space as the client that calls it or in a Microsoft Transaction Server process.
For more information about creating Visual FoxPro Automation servers, see Creating Automation Servers, in Chapter 16 of the Programmer's Guide.
The following topics describe the new and improved Visual FoxPro 6.0 Automation server features.
Visual FoxPro Automation servers now support Apartment Model Threading. The Microsoft Transaction Server takes advantage of servers marked as apartment threaded and offers better thread protection and scalability.
Each apartment model object (such as a Visual FoxPro Automation server) may only be entered by one thread, the thread that created the object (for example, called CoCreateInstance in Microsoft Visual C++. However, an object server (such as Microsoft Transaction Server) can support multiple objects, each being entered simultaneously by different threads. Common data held by the object server must be protected against thread collisions. The object server creates an apartment model object in the same thread that called CoCreateInstance. Calls to the object from the apartment thread are not marshaled.
For more information about apartment model threading, search for “Apartment-Model Threading in Visual Basic” in the the MSDN library.
The new apartment model threading support requires that in-process .dll Automation servers not have user-interfaces. In Visual FoxPro 5.0, one could create (although it was not recommended) an in-process .dll Automation server that had a user-interface such as a form. The form could be used only for display because the form events are not supported. In Visual FoxPro 6.0, any attempts to create a user-interface in an in-process .dll Automation generates an error.
An out-of-process .exe Automation server can have a user-interface. A new Visual FoxPro 6.0 function, SYS(2335), has been added so you can disable modal events for an out-of-process .exe Automation server, which may be deployed remotely without intervention from a user. Modal events are created by user-defined modal forms, system dialogs, the MESSAGEBOX( ) function and the WAIT command, and so on.
Visual FoxPro 6.0 now supports both early (vtable) binding as well as the existing IDispatch interface (together known as dual-interface support). Early (vtable) binding provides performance benefits for Automation controllers such as Visual Basic and the Microsoft Transaction Server that support early (vtable) binding.
A single Visual FoxPro 6.0 runtime, Vfp6r.dll, no longer services multiple in-process .dll Automation servers. Each in-process .dll now uses a separate instance of the Vfp6r.dll runtime. The following rules determine how in-process .dlls use the Vfp6r.dll runtime:
Visual FoxPro 6.0 now supports intrinsic (Visual FoxPro) properties, events, and methods in an Automation server’s type library. Only properties declared as Public are included in the type library; protected and hidden properties do not appear in the type library. Note that the Visual FoxPro Release method isn’t included in the type library because it already exists as a COM method.
Both PUBLIC custom user-defined properties and methods appear in Visual FoxPro type libraries as long as they are marked Public. For methods, Visual FoxPro also includes a return value type (variant) and list of parameters (variants) parsed from the original method definition.
Note that in Visual FoxPro 6.0 a single Help file can be designated the type library.
Visual FoxPro Automation servers are now more robust, so they can more gracefully terminate when an exception occurs. When exceptions occur in a Visual FoxPro 6.0 Automation server, the Automation server now sets the COM ErrorInfo object (via IErrorInfo) and cancels out of the current method. The Automation client has the option of releasing the Visual FoxPro Automation server or handling the exception, based on the information in the COM ErrorInfo object (and the client has access to the COM ErrorInfo object).
A new function, COMRETURNERROR( ), has been added to Visual FoxPro 6.0 to handle errors that occur on an Automation server. COMRETURNERROR( ) can be used in the Error method, and populates the COM exception structure with information that Automation clients can use to determine the source of Automation server errors. For more information, see COMRETURNERROR( ) in the Language Reference.
Visual FoxPro 5.0 passes arrays to COM objects (such as Automation servers created in Visual FoxPro, Visual Basic, or Visual C) by value; the array elements are the same after a method call, and the COM object changes aren’t propagated to the elements on the client. This restriction prevents passing large amounts of data back and forth between Visual FoxPro 5.0 and COM objects.
Also, the array passed to the COM object is assumed be a one-based array, meaning that the first element, row, and column in the array is referenced with 1 (for example, Myarray[1]). However, some COM objects require that the array passed is zero-based (the first element, row, and column in the array is referenced with 0; for example, Myarray[0]).
A new Visual FoxPro 6.0 function, COMARRAY( ), lets you specify how an array is passed to a COM object, and lets you specify if the array is zero or one-based. For more information, see COMARRAY( ) in the Language Reference.
Note that COMARRAY( ) is only used when arrays are passed to COM objects using the following syntax:
oComObject.Method(@MyArray)
If the @ token is omitted, only the first element of the array is passed to the COM object and COMARRAY( ) has no effect. This is the same behavior for earlier versions of Visual FoxPro.
Because in-process .dll and out-of-process .exe Automation servers are invoked through class instantiation, it isn’t necessary to specify a main file for them. In Visual FoxPro 6.0 you can now build an in-process .dll or an out-of-process .exe Automation server without first specifying a main file in the Project Manager.
The following table lists the properties and functions added to Visual FoxPro 6.0 to make it easier to manage Automation clients and servers. See each topic for further information.
| New Server Improvements language | Description |
| COMARRAY( ) Function | Specifies how arrays are passed to COM objects. |
| COMCLASSINFO( ) Function | Returns registry information about a COM object such as a Visual FoxPro Automation server. |
| CREATEOBJECTEX( ) Function | Creates an instance of a registered COM object (such as a Visual FoxPro Automation server) on a remote computer. For a Visual FoxPro in-process .dll, you can use Microsoft Transaction Server to create an instance of the .dll on a remote computer. |
| COMRETURNERROR( ) Function | Populates the COM exception structure with information that Automation clients can use to determine the source of Automation server errors. |
| ServerName Property | Contains the full path and file name for an Automation server. The ServerName property is a property of the Application object. |
| StartMode Property | Contains a numeric value that indicates how the instance of Visual FoxPro was started. |
| SYS(2334) – Automation Server Invocation Mode | Returns a value indicating how a Visual FoxPro automation server method was invoked. |
| SYS(2335) – Unattended Server Mode | Enables or disables support for modal states in distributable Visual FoxPro .exe Automation servers. |
The following section provides additional programming information for Automation servers.
The Application object isn't exposed in an Automation server's type library. This prevents access to the Application object's DoCmd and Eval methods, which can potentially provide access to the entire Visual FoxPro language. You can expose the Application object by creating a custom property and setting its value to the Application object, or provide a method that accesses the Application object.
Visual FoxPro 6.0 includes two sample ISAPI Automation servers, FoxWeb and FoxIS. These samples manage sending selected records of Visual FoxPro data as HTML back to an Internet browser. For more information about these samples, see FoxISAPI: An OLE Server Sample.