AutoActivate, AutoVerbMenu, DoVerb

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

AutoActivate, AutoVerbMenu, DoVerb

AutoActivate determines the circumstances under which an ActiveX control should start to run. AutoVerbMenu enables a context-sensitive menu that, when invoked, displays actions the control knows how to take, such as Open, Edit or Play. DoVerb is a method for activating, editing or playing ActiveX objects.

Usage

oOLEObject.AutoActivate = nValue
nValue = oOLEObjectAutoActivate

Parameter	Value	Meaning
nValue	0	Manual. The object will not activate on a form, unless programmatically called with the DoVerb method.
	1	GotFocus. Activation takes place when the object receives the focus.
	2	DblClick. Object is activated when double-clicked or when Enter is pressed. This is the default.
	3	Automatic. The Help file claims this setting will determine when to activate the object based upon the "object's normal method of activation." Double-click seems to be the method of choice for all the ActiveX objects we've tried.

Different objects react differently to these settings, depending on the way they were designed. If the default verb of an object is “Play,” as it might be for a sound or other multimedia data, activating the object causes it to play. Most objects have the default verb of “Edit,” which brings forth their editing interface when they are activated.

Setting AutoActivate to 1 (GotFocus) on a really fast machine with lots of RAM has the cool effect of immediately displaying context-sensitive menus and toolbars for embedded objects that support Visual Editing—it looks very slick. On the other hand, if you might be dealing with objects that don’t support the in-place editing feature, or that might be sluggish in updating the interface, you’ll probably want to let the user choose to activate the property only when it needs to be, by setting AutoActivate to 2 (DblClick). Remember, the operator is in charge, and leaving him helpless and clueless that processes are starting on his machine is very bad user-interface diplomacy.

Set AutoActivate to 0 for those situations where you never want the object activated, or if it should be activated only under programmatic control. We haven’t found a use for the Automatic (3) option for this property yet.

Example

ThisForm.OLEBoundControl.AutoActivate = 1  && GotFocus

Usage

oOLEObject.DoVerb( [ nVerb ] )

Parameter	Value	Meaning
nVerb	1, 2, 3...n	The specialized verbs for this object, stored in the Registry.
	0	The default action for this object, typically "Play" for multimedia objects and "Edit" for text-based and graphic objects.
	-1	Activate the object in edit mode, as in-place activation if supported by the object.
	-2	Activate the object in a separate window.
	-3	The Help file states that this verb "hides the creator application for an embedded object." We suspect this may be useful in manipulating an application via DDE or Automation while the application is hidden. The application does not run.
	-4	Activate the object for an in-place editing session only if the object can support in-place editing; otherwise generate error 1426—"OLE error code 0x..." with such informative error messages as "Invalid verb for OLE object," "The server threw an exception" (our favorite) and "Unexpected failure." (So what's an "expected failure"?). You'll want to trap for errors if you use this verb.
	-5	This setting should allow an object to be edited in its own window, if it supports single-click activation. We haven't found one yet.
	-6	This parameter should flush all "undo" information. Again, we haven't yet found OLE servers supporting this feature.

There are several cautions when working with ActiveX objects that bear repeating here. You cannot assume that ActiveX servers registered on one machine will be registered on them all. A new machine can be added to an office, or a catastrophe can easily destroy the Registration File information necessary for manipulating the servers. Check for the availability of OLE servers and specific verbs before attempting to use them. The error messages returned when these functions are unavailable, as we mentioned above, can be particularly uninformative.

Another thing to be wary of is that ActiveX services are typically not identical over the different Windows platforms. The server for WAV files in Win31 installations is a different one than that used in Win95, and an object embedded on one platform may not be accessible on another. In VFP 3, the sample code shown below works in Win31 with OLETypeAllowed as either 0 or 1, but Win95 seems to require 0. In addition, Win31 plays the sound automatically with verbs -1 and -2, while Win95 does not. Under VFP 5 and Windows NT, verb 3 produced “Catastrophic failure” messages when OLETypeAllowed was set to 1, and the far milder “The parameter is incorrect” when set to 0. Really! Someone ought to teach Microsoft that error messages should contain information! As always, we strongly encourage you to test on every platform.

Example

* OLESamp - activation of an OLE sound sample with varied verbs
LOCAL oForm
oForm = CREATEOBJECT("Form")
oForm.AddObject("oleSound","myOLEControl")
oForm.Show()
oForm.oleSound.Visible = .T.
FOR i = 3 TO -3 STEP - 1
  oForm.OleSound.DoVerb(i)
  WAIT WINDOW "DoVerb of " + LTRIM(STR(i)) + CHR(13) + ;
              "Press any key to continue..."
NEXT
RETURN

DEFINE CLASS myOLEControl AS OLEControl
  Height = 20
  OLETypeAllowed = 1
  DocumentFile = "c:\windows\chimes.wav"
  * "c:\winnt40\media\chimes.wav" for Win NT
ENDDEFINE

Usage

oObject.AutoVerbMenu = lShowMenu
lShowMenu = oObject.AutoVerbMenu

This setting determines whether calling up a context menu (by right-mouse-clicking or Shift+F10 when the object has focus) displays the verbs associated with the OLE object. If this is set .F., no automatic context menu appears, although you could fire your own from the RightClick event. Each object has verbs according to its type and what servers are installed on the machine. If no verbs are available, no menu appears.

Example

* An extension of the form above, this one has
* AutoVerbMenu turned on so that you can call up the
* context menu, and a close button to support the needed
* READ EVENTS.

LOCAL oForm
oForm = CREATEOBJECT("Form")
oForm.AddObject("oleSound","myOLEControl")
oForm.AddObject("cmdClose","cmdClose")
WITH oForm.cmdClose
  .TOP = oForm.Height - (.Height + 10)
  .Left = 0.5 * (oForm.Width - .Width)
  .Visible = .T.
ENDWITH
oForm.Show()
oForm.oleSound.Visible = .T.
read events
RETURN

DEFINE CLASS myOLEControl AS OLEControl
  Height = 20
  OLETypeAllowed = 1
  DocumentFile = "c:\winnt40\media\chimes.wav" && for Win NT
  AutoVerbMenu = .T.
ENDDEFINE

Define class cmdClose as CommandButton
  AutoSize = .T.
  Caption = "Close"
  Procedure Click
    ThisForm.Release()
    Clear Events
  EndProc
EndDefine