CALLTHIS function

Microsoft Office ShapeSheet

CALLTHIS function

Calls a procedure in a Microsoft Visual Basic for Applications (VBA) project.

Syntax

CALLTHIS("procedure",["project"],[arg1,arg2,…])

procedure

The name of the procedure to call; required string.

project

Optional string. The project that contains the procedure.

arg

An argument of any type that can include number, string, date, and currency values; passed as parameters to the procedure.

Remarks

In the VBA project, procedure is defined as follows:

procedure(shpObj As Visio.shape [arg1 As type, arg2 As type...])

where shpObj is a reference to the Shape object that contains the CALLTHIS formula being evaluated, and arg1, arg2... are the arguments specified in that formula.

Notice that shpObj is very much like the "this" argument passed to a C++ member procedure; hence the name "CALLTHIS." In effect, a cell that contains a formula with CALLTHIS is saying, "Call this procedure and pass it a reference to my shape."

If project is specified, Visio scans all open documents for the one containing project and calls procedure in that project. If project is omitted or null (""), procedure is assumed to be in the VBA project of the document that contains the CALLTHIS formula being evaluated.

Numbers in arg1, arg2… are passed in external units. For example, if you pass the value of the Height cell from a 3-cm-tall shape, 3 is passed. To pass different units with a number, use the FORMATEX function or explicitly coerce units by adding a null number-unit pair, for example, 0 ft + Height.

The second comma in the CALLTHIS function is optional. It corresponds to the number of additional parameters added to your procedure. If you do not use any additional parameters, except shpObj as Visio.Shape, do not add the second comma—use CALLTHIS("",). If you add two additional parameters, for example, use CALLTHIS("",,,).

The CALLTHIS function always evaluates to 0, and the call to procedure occurs during idle time after the recalculation process finishes. Procedure can return a value, but Visio ignores it. Procedure can simulate returning a value that Visio can recognize by setting the formula or result of another cell in the document, but not the cell that called procedure unless you want to overwrite the CALLTHIS formula.

The CALLTHIS function differs from the RUNADDON function in that a document's project need not reference another project in order to call into that project.

Note VBA code invoked as a result of the Visio instance evaluating a CALLTHIS function in a formula should not close the document containing the cell using the function because an application error results and Visio terminates.

If you need to close the document containing the cell that uses the CALLTHIS function, use one of the following techniques:

  • Close the document from non-VBA code.
  • Close the document from a project other than the one that is closing.
  • Post window messages to close windows into the document rather than closing the document.

Example 1

CALLTHIS("p",,FORMATEX(Height,"#.00 u",,"cm"))

Calls the procedure named p located in a module and passes the value of Height in centimeters, such as 7.62 cm.

Example 2

CALLTHIS("q",,0 cm.+Height,Sheet.2!Width)

Calls the procedure named q located in a module and passes the cell's height in centimeters and Sheet.2's width in internal units.

Example 3

Use the following procedure in the ThisDocument class module.

Sub A(shpObj As Visio.Shape)
    MsgBox "Click OK."
End Sub
Sub B(shpObj As Visio.Shape, strA As String)
    MsgBox strA
End Sub
Sub C(shpObj As Visio.Shape, strA As String, strB As String)
    MsgBox strA & strB
End Sub

Use any of the following syntax in a shape's EventDblClick cell with the procedures above.

CALLTHIS("ThisDocument.A",)

CALLTHIS("ThisDocument.B",,"Click")

CALLTHIS("ThisDocument.C",,"Click", " OK.")