GetFormulas[U] method
Returns the formulas of many cells.
Version added
4.5
Syntax
| |
|
object |
Required. An expression that returns a Page, Master, Shape, or Style object. |
|
SID_SRCStream |
Required Integer. Stream identifying cells to be queried. |
|
formulas |
Required Variant. Array that receives formulas of queried cells. |
Remarks
The GetFormulas method is like the Formula method 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 GetFormulas method is a specialization of the GetResults method, which can be used to obtain cell formulas or results. Setting up a call to the GetFormulas method involves slightly less work than setting up the GetResults method.
For Shape or Style objects you can use the GetFormulas method to get formulas of any set of cells.
For a Page or Master object you can use the GetFormulas method to get formulas of any set of cells in any set of shapes of the page or master.
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. GetFormulas interprets the stream as:
{ sectionIdx, rowIdx, cellIdx }nwhere sectionIdx is the section index of the desired cell, rowIdx is its row index and cellIdx is its cell index.
- For Page or Master objects, SID_SRCStream should be a one-dimensional array of 4n 2-byte integers for n >= 1. The GetFormulas method interprets SID_SRCStream as:
{ sheetID, sectionIdx, rowIdx, cellIdx }nwhere sheetID is the ID property of the Shape object on the page or master whose cell formula is desired.
Note If the sheetID in an entry is visInvalShapeID (-1) or if the bottom byte of sectionIdx is visSectionInval (255), then the entry will be ignored and an empty variant will be returned in the corresponding results array entry. The motivation for this is that the same SID_SRCStream array can be used on several calls to GetFormulas, SetFormulas, and similar methods with the caller only needing to make minor changes to the stream between calls.
If the GetFormulas 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 GetFormulas 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 GetFormulas method fails if formulas is Null.
Note Beginning with Visio 2000, you can refer to Visio shapes, masters, styles, pages, rows, and layers using local and universal names. When a user names a shape, for example, the user is specifying a local name. Universal names are not visible through 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 using local syntax. Use the GetFormulasU method to get more than one formula using universal syntax.