DocumentFile, HostName

DocumentFile is a property of OLE bound and unbound controls. It allows you to query or, under limited circumstances, set the linked file. HostName allows you to specify your application’s name as you wish it to appear when editing OLE objects.

Usage

cFileName = oleObject.DocumentFile
oleObject.DocumentFile = cFileName
cHostName = oleObject.HostName
oleObject.HostName = cHostName

DocumentFile returns the name of the file associated with a linked object—either an OLEBoundControl or an unbound OLEControl. It’s blank for an object with embedded data. This is the only way we know of to tell the difference. DocumentFile is read-only at runtime, but may be set for an OLEControl only in a class definition. We’re a bit surprised at how restrictive this is. You can’t place an embedded or linked OLE control on a form without specifying the name of the document. We would think you could at least change this property on the property sheet in design mode.

HostName is a setting for purely cosmetic purposes. In FoxPro 2.x, a number of users (well, at least two) complained that “FoxPro” was prominently displayed when editing OLE objects in their server application (equivalent to OLE servers which don’t support in-place editing in version 3.x). When saving an application, a dialog appeared, prompting “Do you want to save changes to FoxPro…” and, finally, the menu prompt under the file pad offers the option “Exit and return to FoxPro.” HostName allows you to replace the text in all of these places with your own application’s name.

In some OLE servers, leaving HostName blank leads to some funny dialogs, such as “Do you want to save changes to ?” and menu prompts “Exit and Return to.” This is a lack of grace on their part, and not necessarily FoxPro’s fault. Similarly, some applications do not respect the case of the HostName string supplied, instead displaying lowercase only. If you have an application or company name where the case is significant, you’ll find this to be a real inconvenience. But don’t blame the fox for this one.

Example

* Creates a form with a sound player olecontrol
* and a close button. Double-click the olecontrol
* to play the sounds.
* AutoVerbMenu provides a context menu to the control
* Right-mouse-click and select 'Edit' to bring up the
* Sound Player. Note the File menu has the option
* "Exit and Return to <your version of FoxPro>"
* and the Sound Player title bar shows the HostName
oForm = CREATEOBJECT("frmSound")
oForm.Show()
READ EVENTS
RETURN

DEFINE CLASS frmSound AS form
  ADD OBJECT cmdClose AS CommandButton
  ADD OBJECT oleSound AS OleControl ;
    WITH DocumentFile = "C:\WinNT40\Media\Chimes.WAV"
  Procedure Init
    WITH This.oleSound
      .AutoVerbMenu = .T.
      .HostName = VERSION()
      * Center the oleControl
      .Height = 2 * .Height
      .Top = 0.5 * (ThisForm.Height - .Height)
      .Left = 0.5 * (ThisForm.Width - .Width)
    ENDWITH
    WITH This.cmdClose
      * Center the Close button on the form bottom
      .Caption = "Close"
      .Top = ThisForm.Height - (.Height+5)
      .Left = 0.5 * (ThisForm.Width - .Width)
    ENDWITH
  EndProc
  Procedure cmdClose.Click
    CLEAR EVENTS
  EndProc
ENDDEFINE

See Also

OLEBoundControl, OLEControl