Share via

GetFormulasU Method [Visio 2003 SDK Documentation]

  • Article

As it applies to the Master or Page object.

Returns the formulas of many cells.

object**.GetFormulasU**    SID_SRCStream, formulas

object     Required. An expression that returns a Master or Page object.

SID_SRCStream     Required Integer. Stream identifying cells to be queried.

formulas     Required Variant. Array that receives formulas of queried cells.

Version added

4.5

Remarks

The GetFormulasU method is like the FormulaU property of a Cell object, except you can use it to obtain the formulas of many cells at once, rather than one cell at a time. The GetFormulasU method is a specialization of the GetResults method, which can be used to obtain cell formulas or results. Setting up a call to the GetFormulasU method involves slightly less work than setting up the GetResults method.

You can use the GetFormulasU method to get formulas in universal syntax of any set of cells in any set of shapes of the page or master.

SID_SRCStream is an array of 2-byte integers. SID_SRCStream should be a one-dimensional array of 4n 2-byte integers for n >= 1. The GetFormulasU method interprets SID_SRCStream as:

{sheetID, sectionIdx, rowIdx, cellIdx}n

sheetIDIDShape

Note   If the sheetID in an entry is visInvalShapeID (-1) or if the bottom byte of sectionIdx is visSectionInval (255), the entry will be ignored and an empty variant will be returned in the corresponding results array entry. The reason for this is that the same SID_SRCStream array can be used on several calls to GetFormulasU, SetFormulas, and similar methods with the caller only needing to make minor changes to the stream between calls.

If the GetFormulasU method succeeds, formulas returns a one-dimensional array of n variants indexed from 0 to n - 1. Each variant returns a formula as a string. Formulas is an out argument that is allocated by the GetFormulasU method, which passes ownership back to the caller. The caller should eventually perform the SafeArrayDestroy procedure on the returned array. Note that the SafeArrayDestroy procedure has the side effect of clearing the variants referenced by the array's entries, hence deallocating any strings the GetFormulasU method returns. (Microsoft Visual Basic and Visual Basic for Applications take care of this for you.) The GetFormulasU method fails if formulas is Null.

Note  Beginning with Microsoft Visio 2000, you can use both local and universal names to refer to Visio shapes, masters, documents, pages, rows, add-ons, cells, hyperlinks, styles, fonts, master shortcuts, UI objects, and layers. When a user names a shape, for example, the user is specifying a local name. Beginning with Microsoft Office Visio 2003, the ShapeSheet spreadsheet displays only universal names in cell formulas and values. (In prior versions, universal names were not visible in the user interface.)

As a developer, you can use universal names in a program when you don't want to change a name each time a solution is localized. Use the GetFormulas method to get more than one formula when you are using local syntax. Use the GetFormulasU method to get more than one formula when you are using universal syntax.

As it applies to the Shape or Style object.

Returns the formulas of many cells.

object**.GetFormulasU**    SID_SRCStream, formulas

object     Required. An expression that returns a Shape or Style object.

SID_SRCStream     Required Integer. Stream identifying cells to be queried.

formulas     Required Variant. Array that receives formulas of queried cells.

Version added

4.5

Remarks

The GetFormulasU method is like the FormulaU property of a Cell object, except you can use it to obtain the formulas of many cells at once rather than one cell at a time. The GetFormulasU method is a specialization of the GetResults method, which can be used to obtain cell formulas or results. Setting up a call to the GetFormulasU method involves slightly less work than setting up the GetResults method.

You can use the GetFormulasU method to get formulas of any set of cells.

SID_SRCStream is an array of 2-byte integers. For Shape or Style objects, SID_SRCStream should be a one-dimensional array of 3n 2-byte integers for some n >= 1. GetFormulasU interprets the stream as:

{sectionIdx, rowIdx, cellIdx}n

where sectionIdx is the section index of the desired cell, rowIdx is its row index and cellIdx is its cell index.

Note   If the sheetID in an entry is visInvalShapeID (-1) or if the bottom byte of sectionIdx is visSectionInval (255), the entry will be ignored and an empty variant will be returned in the corresponding results array entry. This is because the same SID_SRCStream array can be used on several calls to GetFormulasU, SetFormulas, and similar methods with the caller only needing to make minor changes to the stream between calls.

If the GetFormulasU method succeeds, formulas returns a one-dimensional array of n variants indexed from 0 to n - 1. Each variant returns a formula as a string. Formulas is an out argument that is allocated by the GetFormulasU method, which passes ownership back to the caller. The caller should eventually perform the SafeArrayDestroy procedure on the returned array. Note that the SafeArrayDestroy procedure has the side effect of clearing the variants referenced by the array's entries, hence deallocating any strings the GetFormulas method returns. (Microsoft Visual Basic and Visual Basic for Applications take care of this for you.) The GetFormulasU method fails if formulas is Null.

Note  Beginning with Microsoft Visio 2000, you can use both local and universal names to refer to Visio shapes, masters, documents, pages, rows, add-ons, cells, hyperlinks, styles, fonts, master shortcuts, UI objects, and layers. When a user names a shape, for example, the user is specifying a local name. Beginning with Microsoft Office Visio 2003, the ShapeSheet spreadsheet displays only universal names in cell formulas and values. (In prior versions, universal names were not visible in the user interface.)

As a developer, you can use universal names in a program when you don't want to change a name each time a solution is localized. Use the GetFormulas method to get more than one formula when you are using local syntax. Use the GetFormulasU method to get more than one formula when you are using universal syntax.

Example

As it applies to the Page object.

The following macro shows how to use the GetFormulasU method. It assumes that there is an active Visio page that has at least three shapes on it. It uses GetFormulasU to get the width of shape 1, the height of shape 2, and the angle of shape 3.

This example uses the GetFormulasU method of the Page object to get three cell formulas The input array has four slots for each cell, as it also would for Master objects. For Shape or Style objects, only three slots would be needed for each cell (section, row, and cell).

Public Sub GetFormulasU_Example() 

    On Error GoTo HandleError 

    Dim aintSheetSectionRowColumn(1 To 3 * 4) As Integer 

    aintSheetSectionRowColumn(1) = ActivePage.Shapes(1).ID 
    aintSheetSectionRowColumn(2) = visSectionObject 
    aintSheetSectionRowColumn(3) = visRowXFormOut 
    aintSheetSectionRowColumn(4) = visXFormWidth 

    aintSheetSectionRowColumn(5) = ActivePage.Shapes(2).ID 
    aintSheetSectionRowColumn(6) = visSectionObject 
    aintSheetSectionRowColumn(7) = visRowXFormOut 
    aintSheetSectionRowColumn(8) = visXFormHeight 

    aintSheetSectionRowColumn(9) = ActivePage.Shapes(3).ID 
    aintSheetSectionRowColumn(10) = visSectionObject 
    aintSheetSectionRowColumn(11) = visRowXFormOut 
    aintSheetSectionRowColumn(12) = visXFormAngle 

    'Return the formulas of the cells. 
    Dim avarFormulaArray() As Variant 
    ActivePage.GetFormulasU aintSheetSectionRowColumn, avarFormulaArray

    Debug.Print "Shape 1 width is "; avarFormulaArray(0)
    Debug.Print "Shape 2 height is "; avarFormulaArray(1)
    Debug.Print "Shape 3 angle is "; avarFormulaArray(2)


Exit Sub   

HandleError: 
    MsgBox "Error" 
Exit Sub  
 
End Sub

Applies to | Master object | Page object | Shape object | Style object