Add Method [Visio 2003 SDK Documentation]

As it applies to the AccelItems, AccelTables, Hyperlinks, Masters, MenuItems, Menus, MenuSets, Pages, ToolbarItems, Toolbars, and ToolbarSets collections.

Adds a new object to a collection.

objRet = object**.Add**

objRet    The new object added to the collection.

object    Required. An expression that returns an object in the Applies to list.

Version added

2.0

Remarks

All properties of the new object are initialized to zero, so you need to set only the properties that you want to change.

Pages.Add is disabled when markup tracking is on in Microsoft Office Visio.

As it applies to the Addons collection.

Adds a new Addon object to an Addons collection.

addonObj = object**.Add** (fileName)

addonObj    The new Addon object added to the Addons collection.

object    Required. An expression that returns an Addons collection.

fileName    Required String. The name of the add-on.

Version added

2.0

Remarks

The Add method adds an EXE or VSL file to the collection and returns an Addon object if the string expression specifies an EXE file, or Nothing if the string expression specifies a VSL file.

As it applies to the Documents collection.

Adds a new Document object to the Documents collection.

docObj = object**.Add** (fileName)

docObj    The new Document object added to the Documents collection.

object    Required. An expression that returns a Documents collection.

fileName     Required String. The type or file name of the document to add; if you do not include a path, Visio searches the folder or folders designated in the Application object's TemplatePaths property and all published templates, including published third-party templates.

Version added

2.0

Remarks

To create a new drawing based on no template, pass a zero-length string ("") to the Add method.

To create a new drawing based on a template, pass "templatename.vst" to the Add method. Visio opens stencils that are part of the template's workspace and copies styles and other settings associated with the template to the new document. If the template file name is invalid, no document is returned and an error is generated.

To create a new stencil based on no stencil, pass ("vss").

To open a copy of a stencil, pass ("stencilname.vss").

To open a copy of a drawing, pass ("drawingname.vsd").

Note  Opening a copy of a stencil or drawing is equivalent to selecting Copy in the Open list box of the Open dialog box or using the OpenEx method with the visOpenCopy flag.

As it applies to the EventList collection.

Adds an Event object that runs an add-on when an event occurs. The Event object is added to the EventList collection of the source object whose events you want to receive.

eventObj = object**.Add** (eventCode, action, target, targetArgs)

eventObj    The new Event object added to the EventList collection.

object    Required. An expression that returns an EventList collection.

eventCode    Required Integer. The event(s) to capture.

action   Required Integer. The action to perform. Must be visActCodeRunAddon, a member of VisEventCodes in the Visio type Library.

target    Required String. The name of your add-on.

targetArgs    Required String. The string that is passed to your Event object to set its TargetArgs property.

Version added

4.1

Remarks

The source object whose EventList collection contains the Event object establishes the scope in which the events are reported. Events are reported for the source object and objects lower in the object model hierarchy. For example, to run an add-on when a particular document is opened, add an Event object for the DocumentOpened event to the EventList collection of that document. To run an add-on when any document is opened in an instance of the application, add the Event object to the EventList collection of the Application object.

Creating Event objects is a common way to handle events from C++ or other non-Microsoft Visual Basic solutions. When you use the Visual Basic WithEvents keyword to handle events, all the events in a source object's event set fire, but when you create Event objects, your program will only be notified of the events you select. Depending on your solution, this may result in improved performance.

Event objects that run add-ons can be persistent: that is, they can be stored with a Visio document. To be persistent, an Event object's Persistent and Persistable properties must both be True.

The arguments passed to the Add method set the initial values of the Event object's Event, Action (visActCodeRunAddon), Target, and TargetArgs properties.

Event codes are declared by the Visio type library and have the prefix visEvt. Event codes are often a combination of constants. For example, visEvtAdd+visEvtDoc is the event code for the DocumentAdded event. To find an event code for the event you want to create, see Event codes.

To create an Event object that advises the caller's sink object about an event, see the AddAdvise method.

As it applies to the Layer object.

Adds a Shape object to a Layer object.

object**.Add**(shapeObj, fPreserveMembers)

object    Required. An expression that returns a Layer object.

shapeObj    Required. The new Shape object added to the Layer object.

fPreserveMembers    Required Integer. Zero to remove subshapes from any previous layer assignments; non-zero to preserve layer assignments.

Version added

2.0

Remarks

If the shape is a group and fPreserveMembers is non-zero, the component shapes of the group retain their current layer assignments and are also added to this layer. If fPreserveMembers is zero, the component shapes are reassigned to this layer and lose their current layer assignments.

As it applies to the Layers collection.

Adds a new Layer object to a Layers collection.

layerObj = object**.Add** (layerName)

layerObj    The new Layer object added to the Layers collection.

object    Required. An expression that returns a Layers collection.

layerName    Required String. The name of the new layer.

Version added

2.0

As it applies to the Styles collection.

Adds a new Style object to a Styles collection.

styleObj = object**.Add**(newStyleName, basedOnName, fIncludesText, fIncludesLine, fIncludesFill)

styleObj    The new Style object added to the Styles collection.

object    Required. An expression that returns a Styles collection.

newStyleName    Required String. The new style name.

basedOnName    Required String. The name of the style on which to base the new style.

fIncludesText    Required Integer. Zero to disable text attributes, or non-zero to enable them.

fIncludesLine    Required Integer. Zero to disable line attributes, or non-zero to enable them.

fIncludesFill    Required Integer. Zero to disable fill attributes, or non-zero to enable them.

Version added

2.0

Remarks

To base the new style on no style, pass a zero-length string ("") for the basedOnName argument.

As it applies to the Windows collection.

Adds a new Window object to the Windows collection.

objRet = object.Add ([varCaption][, varFlags] [, varType][, varLeft][, varTop][, varWidth] [, varHeight][, bstrMergeID][, bstrMergeClass] [, nMergePosition])

objRet    The new Window object added to the collection.

object    Required. An expression that returns a Windows collection.

varCaption    Optional Variant. The title of window; default is "Untitled".

varFlags    Optional Variant. Initial window state. Can contain any combination of VisWindowStates constants declared in the Visio type library; default varies based on the varType.

varType     Optional Variant. Type of new window. Can be any one of the VisWinTypes constants declared in the Visio type library. Defaults to visStencilAddon for Application.Windows; defaults to visAnchorBarAddon for Window.Windows

varLeft    Optional Variant. Position of the left side of the window.

varTop    Optional Variant. Position of the top of the window.

varWidth    Optional Variant. Width of the client area of the window.

varHeight    Optional Variant. Height of the client area of the window.

bstrMergeID    Optional Variant. Merge ID of the window.

bstrMergeClass    Optional Variant. Merge class of the window.

nMergePostition    Optional Variant. Merge position of the window.

Version added

2000

Remarks

Use this method to get an empty parent frame window within the Visio window space that you can populate with child windows. You must be in the Visio process space (for example, in a DLL or VSL-based add-on) to use the Window object returned by this method as a parent to your windows.

Use the value returned by the WindowHandle32 property as an HWND for use as a parent to your own windows.

Example

As it applies to the Addons collection.

The following macro shows how to add an Addon object to the Addons collection.

Before running this macro, replace path\filename with a valid path and file name for an add-on in your Visio project.

Public Sub AddAddon_Example() 
 
    Dim vsoAddons As Visio.Addons 
    Dim vsoAddon As Visio.Addon 

    'Add an add-on to the Addons collection.
    Set vsoAddons = Visio.Addons 
    Set vsoAddon = vsoAddons.Add("path\filename") 

End Sub  

As it applies to the Documents collection.

The following macro shows how to add Document objects such as templates, stencils, and drawings to the Documents collection.

Before running this macro, replace Myfile.vsd with a valid .vsd file.

Public Sub AddDocument_Example() 

    Dim vsoDocument As Visio.Document

    'Add a Document object based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst") 

    'Add a Document object based on a drawing (creates a copy of the drawing).
    Set vsoDocument = Documents.Add("Myfile.vsd")
 
    'Add a Document object based on a stencil (creates a copy of the stencil).
    Set vsoDocument = Documents.Add("Basic Shapes.vss") 

    'Add a Document object based on no template.
    Set vsoDocument = Documents.Add("") 

End Sub  

As it applies to the EventList collection.

The following example shows how to add an Event object that runs an add-on to the EventList collection of the source object, in this case a Document object, whose events you want to receive.

Before running this macro, replace path\filename with a valid path and file name for an executable add-on (EXE) in your Visio project. The add-on should take no arguments.

Public Sub AddEvent_Example()

    Dim vsoAddons As Visio.Addons 
    Dim vsoEventList As Visio.EventList 
    Dim vsoDocument As Visio.Document 
    Dim vsoEvent As Visio.Event 
    Dim vsoAddon As Visio.Addon

    'Add a document based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst") 

    'Add an add-on to the Addons collection.
    Set vsoAddons = Visio.Addons
    Set vsoAddon = vsoAddons.Add("path\filename")
 
    'Add a BeforeDeleteSelection event to the EventList collection
    'of the Document object. The event will start your add-on,
    'which takes no arguments.
    Set vsoEventList = vsoDocument.EventList 
    Set vsoEvent = vsoEventList.Add(visEvtCodeBefSelDel, _ 
      visActCodeRunAddon, _ 
      "path\filename", "") 

End Sub  

As it applies to the Layer object.

The following example shows how to use the Add method to add Shape objects to a Layer object. When the Shape object you add to a Layer object is a group shape, use the fPreserveMembers argument of the Add method to specify whether the component shapes of the group retain or lose their previous layer assignments. If the shape you add is not a group shape, the fPreserveMembers argument has no effect, but is still required.

In the example, two new layers are created. Two rectangle shapes are drawn and then added to the first layer. Subsequently, the rectangles are grouped into a group shape. The group shape is then selected and duplicated, and the duplicate group shapes are added to the second layer in two different ways.

Layer assignments of the component shapes of vsoShapeGroup2 are retained by passing a non-zero value for the fPreserveMembers argument of the Add method, but previous layer assignments of the component shapes of vsoShapeGroup1 are lost when zero is passed to the Add method for that argument. As a result, the component shapes of vsoShapeGroup1 are assigned only to vsoLayer2, while the components of vsoShapeGroup2 are assigned to both vsoLayer1 and vsoLayer2.

Public Sub AddShapesToLayer_Example()
 
    Dim vsoDocument As Visio.Document 
    Dim vsoPages As Visio.Pages 
    Dim vsoPage As Visio.Page 
    Dim vsoLayers As Visio.Layers 
    Dim vsoLayer1 As Visio.Layer 
    Dim vsoLayer2 As Visio.Layer 
    Dim vsoShape1 As Visio.Shape 
    Dim vsoShape2 As Visio.Shape 
    Dim vsoShapeGroup1 As Visio.Shape 
    Dim vsoShapeGroup2 As Visio.Shape 

    'Add a Document object based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst") 

    'Get the Pages collection and add a page to the collection.
    Set vsoPages = vsoDocument.Pages 
    Set vsoPage = vsoPages.Add 

    'Get the Layers collection and add two layers
    'to the collection. 
    Set vsoLayers = vsoPage.Layers 
    Set vsoLayer1 = vsoLayers.Add("MyLayer") 
    Set vsoLayer2 = vsoLayers.Add("MySecondLayer") 

    'Draw two rectangles.
    Set vsoShape1 = vsoPage.DrawRectangle(3, 3, 5, 6) 
    Set vsoShape2 = vsoPage.DrawRectangle(4, 4, 6, 7) 

    'Assign each rectangle to the first layer.
    vsoLayer1.Add vsoShape1, 0 
    vsoLayer1.Add vsoShape2, 0 

    'Select the two rectangles and group them.
    ActiveWindow.SelectAll 
    ActiveWindow.Selection.Group 

    'Duplicate the group and set each group as a Shape object.
    Set vsoShapeGroup1 = vsoPage.Shapes(1) 
    vsoShapeGroup1.Duplicate
    Set vsoShapeGroup2 = vsoPage.Shapes(2)
 
    'Add the first grouped shape to the second layer.
    'This group's component shapes are added to the layer
    'but lose their previous layer assignment.
    vsoLayer2.Add vsoShapeGroup1, 0 

    'Add the second grouped shape to the second layer.
    'This group's component shapes are added to the layer
    'but retain their previous layer assignment.
    vsoLayer2.Add vsoShapeGroup2, 1 

End Sub  

As it applies to the Layers collection.

The following macro shows how to add a Layer object to the Layers collection.

Public Sub AddLayer_Example()
    
    Dim vsoDocument As Visio.Document 
    Dim vsoPages As Visio.Pages 
    Dim vsoPage As Visio.Page 
    Dim vsoLayers As Visio.Layers 
    Dim vsoLayer As Visio.Layer
 
    'Add a document based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst") 

    'Get the Pages collection and add a page to the collection.
    Set vsoPages = vsoDocument.Pages 
    Set vsoPage = vsoPages.Add 

    'Get the Layers collection and add a layer named "MyLayer"
    'to the collection.
    Set vsoLayers = vsoPage.Layers 
    Set vsoLayer = vsoLayers.Add("MyLayer") 

End Sub  

As it applies to the Masters and Pages collections.

The following macro shows how to add Master objects to the Masters collection and Page objects to the Pages collection. It also shows how to add documents, layers, styles, events, and add-ons to their corresponding collections.

Before running this macro, replace Myfile.vsd with a valid .vsd file and references to path\filename and filename with a valid path and/or file name to an execuatable add-on (EXE) in your Visio project. The add-on should take no arguments.

Public Sub Add_Example()

    Dim vsoMasters As Visio.Masters 
    Dim vsoAddons As Visio.Addons 
    Dim vsoPages As Visio.Pages 
    Dim vsoEventList As Visio.EventList 
    Dim vsoLayers As Visio.Layers 
    Dim vsoLayer As Visio.Layer 
    Dim vsoStyles As Visio.Styles
 
    Dim vsoDocument As Visio.Document 
    Dim vsoEvent As Visio.Event 
    Dim vsoMaster As Visio.Master 
    Dim vsoPage As Visio.Page 
    Dim vsoShape As Visio.Shape 
    Dim vsoStyle As Visio.Style 
    Dim vsoAddon As Visio.Addon
 
    'Add a document based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst")
 
    'Add a document based on a drawing (creates a copy of the drawing).
    Set vsoDocument = Documents.Add("Myfile.vsd")

    'Add a document based on a stencil (creates a copy of the stencil).
    Set vsoDocument = Documents.Add("Basic Shapes.vss")
 
    'Add a document object based on no template.
    Set vsoDocument = Documents.Add("")
 
    'Get the Pages collection and add a page to the collection.
    Set vsoPages = vsoDocument.Pages 
    Set vsoPage = vsoPages.Add 

    'Get the Masters collection and add a master to the collection.
    Set vsoMasters = vsoDocument.Masters 
    Set vsoMaster = vsoMasters.Add 

    'Get the Layers collection and add a layer named "MyLayer"
    'to the collection.
    Set vsoLayers = vsoPage.Layers 
    Set vsoLayer = vsoLayers.Add("MyLayer")
 
    'Draw a rectangle.
    Set vsoShape = vsoPage.DrawRectangle(3, 3, 5, 6) 

    'Add this shape to MyLayer. The second argument is required but has
    'no effect, because vsoShape is not a group shape. 
    vsoLayer.Add vsoShape, 0

    'Add a style named "My FillStyle" to the Styles collection.
    'This style is based on the Basic style and includes
    'only a Fill style.
    Set vsoStyles = vsoDocument.Styles 
    Set vsoStyle = vsoStyles.Add("My FillStyle", "Basic", False, False, True)

    'Add a style named "My NoStyle" to the Styles collection.
    'This style is based on no style and includes
    'Text, Line, and Fill styles.
    Set vsoStyle = vsoStyles.Add("My NoStyle", "", True, True, True) 

    'Add an add-on to the Addons collection.
    Set vsoAddons = Visio.Addons 
    Set vsoAddon = vsoAddons.Add("path\filename")
 
    'Add a BeforeDeleteSelection event to the EventList collection
    'of the document. The event will start your add-on, which
    'takes no arguments.
    Set vsoEventList = vsoDocument.EventList 
    Set vsoEvent = vsoEventList.Add(visEvtCodeBefSelDel, visActCodeRunAddon, _ 
    "filename", "")

End Sub  

As it applies to the Styles collection.

The following macro shows how to add Style objects to the Styles collection. It shows how to add a new style based on an existing style, as well as how to add a new style created from scratch.

Public Sub AddStyle_Example() 

    Dim vsoDocument As Visio.Document 
    Dim vsoStyles As Visio.Styles 
    Dim vsoStyle As Visio.Style

    'Add a document based on the Basic Diagram template.
    Set vsoDocument = Documents.Add("Basic Diagram.vst")
 
    'Add a style named "My FillStyle" to the Styles collection.
    'This style is based on the Basic style and includes
    'only a Fill style. 
    Set vsoStyles = vsoDocument.Styles 
    Set vsoStyle = vsoStyles.Add("My FillStyle", "Basic", 0, 0, 1) 

    'Add a style named "My NoStyle" to the Styles collection.
    'This style is not based on an existing style and includes
    'Text, Line, and Fill styles. 
    Set vsoStyle = vsoStyles.Add("My NoStyle", "", 1, 1, 1) 

End Sub  

As it applies to the Windows collection.

The following macro shows how to use the Add method to add a Window object to the Windows collection. It creates a new, empty parent frame window, docked to the bottom of the drawing window. Then it populates the new parent frame window with a child window, in this case a form, so that the new window does not appear empty.

Add a form to your Microsoft Visual Basic (VBA) project called frmMain, and then add a TextBox control named txtForm to the form.

The SetParent, FindWindow, and SetWindowLongLib functions are from the Windows API, and are necessary to add the form to the new window.

Add the following code to the form module to resize the text box when the form is resized:

Private Sub UserForm_Resize()
    txtForm.Width = txtForm.Parent.Width - 10
    txtForm.Height = txtForm.Parent.Height - 10
End Sub

Then add the following code to the document project:

Private Declare Function SetParent Lib "user32" (ByVal hWndChild As Long, ByVal hWndNewParent As Long) As Long
Private Declare Function FindWindow Lib "user32" Alias "FindWindowA" (ByVal lpClassName As String, ByVal lpWindowName As String) As Long
Private Declare Function SetWindowLong Lib "user32" Alias "SetWindowLongA" (ByVal hwnd As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long

Private Const GWL_STYLE = (-16)
Private Const WS_CHILD = &H40000000
Private Const WS_VISIBLE = &H10000000

Public Sub AddWindow_Example()

    Dim vsoWindow As Visio.Window
    Dim frmNewWindow As UserForm
    Dim lngFormHandle As Long

    'Add a new Anchor Bar window docked to the bottom of the Visio drawing window
    Set vsoWindow = ActiveWindow.Windows.Add("My New Window", visWSVisible + visWSDockedBottom, visAnchorBarAddon, , , 300, 210)
   
    'Create a new windows form
    Set frmNewWindow = New frmMain
        
    'Get the 32-bit handle of the new window.
    lngFormHandle = FindWindow(vbNullString, "My New Window")
    
    SetWindowLong lngFormHandle, GWL_STYLE, WS_CHILD Or WS_VISIBLE
    SetParent lngFormHandle, vsoWindow.WindowHandle32

End Sub

Applies to | AccelItems collection | AccelTables collection | Addons collection | Documents collection | EventList collection | Hyperlinks collection | Layer object | Layers collection | Masters collection | MenuItems collection | Menus collection | MenuSets collection | Pages collection | Styles collection | ToolbarItems collection | Toolbars collection | ToolbarSets collection | Windows collection

See Also | AddAdvise method | AddAt method | AddAtID method | BasedOn property | Caption property | Event object | Event property | IncludesFill property | IncludesLine property | IncludesText property | MergeClass property | MergeID property | MergePosition property | Name property | Open method | OpenEx method | Persistable property | Persistent property | SetWindowRect method | Shape object | Target property | TargetArgs property | TemplatePaths property | Type property | Visible property | WindowHandle32 property | WindowState property