All Frameworks  Object Hierarchy  This Framework  Indexes

Document (Object)

Represents the document.
The document is the object handled by the operating system as a whole that stores your data in files and databases. It is assigned a type determined by its contents. It may contain other documents with a different type. For example, a PartDocument contains a part and can be contained in a ProductDocument. A workshop is associated with a document to gather all the commands that can be used to create, modify, and edit the objects making up the the document. These commands are arranged in menus and toolbars.

See also:: PartDocument, ProductDocument, DrawingDocument

Cameras: Returns the document's collection of cameras.
CurrentFilter: Returns or sets the current visualization filter.
CurrentLayer: Returns or sets the current layer.
FullName: Returns the document's full file name, including its path.
Path: Returns the document's file path.
ReadOnly: Returns whether the file containing the document can be read only, on can be read and written.
Saved: Returns whether the document has been modified, and thus needs to be saved.
SeeHiddenElements: Returns or sets the document's hidden elements visibility.
Selection: Returns the current selection.

Activate: Activates the document.
Close: Closes the document.
CreateFilter: Creates a new visualization filter from a name and a definition.
CreateReferenceFromName: Creates a reference from a GenericNaming label.
ExportData: Exports the data contained in the document to another format.
GetWorkbench: Returns one of the workbenches of the document.
Indicate2D: Runs an 2D interactive indication command.
Indicate3D: Runs an 3D interactive indication command.
NewWindow: Activates the window which contains the document and duplicates this window.
RemoveFilter: Removes an existing visualization filter.
SaveAs: Saves the document with another name.
Save: Saves the document.

Properties

o Property Cameras(

) As (Read Only)

Returns the document's collection of cameras.

Example:

This example retrieves in CameraCollection the collection of cameras attached to the Doc document.

 Dim CameraCollection As Cameras
 Set CameraCollection = Doc.Cameras

o Property CurrentFilter(

) As

Returns or sets the current visualization filter. CurrentFilter uses the filter name and not its definition. The "All visible" filter means that all layers are visible. For all filters, remind that the current layer is always visible.

Example:

This example makes the filter named "Filter001" as the current visualization filter for the Doc document.

 Doc.CurrentFilter = "Filter001"

o Property CurrentLayer(

) As

Returns or sets the current layer. CurrentLayer uses the layer name and not its number. The "None" layer means that there is no current layer.

Example:

This example makes the layer named "Layer 3" as the current layer for the Doc document.

 Doc.CurrentLayer = "Layer 3"

o Property FullName(

) As (Read Only)

Returns the document's full file name, including its path.

Example:

This example retrieves in DocFullName the Doc document's full file name.

 DocFullName = Doc.FullName

The returned value is like this:

 e:\users\psr\Parts\MyNicePart.CATPart

o Property Path(

) As (Read Only)

Returns the document's file path.

Example:

This example retrieves in DocPath the path where the Doc document is stored.

 DocPath = Doc.Path

The returned value is like this:

 e:\users\psr\Parts

o Property ReadOnly(

) As (Read Only)

Returns whether the file containing the document can be read only, on can be read and written.
True if the file is read-only.

Example:

This example retrieves in IsReadOnly the ability to read, and possibly to write in, the file containing the Doc document.

 IsReadOnly = Doc.ReadOnly

o Property Saved(

) As (Read Only)

Returns whether the document has been modified, and thus needs to be saved.
This happens when the document has changed since either its creation or its last save.

True if the document has not been changed: the document doesn't need to be saved.
False if the document has been changed: the document needs to be saved.

Example:

This example retrieves in HasChanged whether the Doc document needs to be saved.

 HasChanged = NOT Doc.Saved

o Property SeeHiddenElements(

) As

Returns or sets the document's hidden elements visibility.
True if the document's hidden elements are visible to the user.

Example:

This example makes the Doc document's hidden elements visible.

 Doc.SeeHiddenElements = True

o Property Selection(

) As (Read Only)

Returns the current selection. The current selection is the object or the set of objects the end user has selected, usually with the mouse, in the active document displayed in the active window.

Example:

This example returns in CurSel the current selection in the Doc document

 Dim CurSel As Selection
 Set CurSel = Doc.Selection

Methods

o Sub Activate(

)

Activates the document. Activating a document means that this document is the one on which the end user is now working on. This document possibly reconfigures the menu bar and toolbars with its own commands if its type is different from the type of the previous active document. The first window in the window collection which contains this document becomes the active one.

Example:

This example activates the Doc document.

 Doc.Activate()

o Sub Close(

)

Closes the document. This closes all the windows displaying the document. If the document needs to be saved, the end user is prompted whether to save the document, or to close it anyway.

Example:

This example closes the Doc document

 Doc.Close()

o Sub CreateFilter(		`iFilterName`,
		`iFilterDefinition`)

Creates a new visualization filter from a name and a definition. Fails if there is already a filter named iFilterName.

Parameters:

iFilterName

The filter name.

iFilterDefinition

The filter definition

Example:

This example creates the filter named "Filter001" and with "layer= 2 & layer= 1" definition for the Doc document.

 Doc.CreateFilter ("Filter001", "layer= 2 & layer= 1")

o Func CreateReferenceFromName( iLabel) As

Creates a reference from a GenericNaming label. Each kind of document provides a specific implementation.

Parameters:

iLabel: The GenericNaming identification for an object.

Returns:

The reference to the object.

o Sub ExportData(		`fileName`,
		`format`)

Exports the data contained in the document to another format.

Parameters:

fileName: The name of the exported file
format: The name of the format

Example:

This example writes the Doc document in the IGES format under the IGESDoc name.

 Doc.ExportData("IGESDoc", "igs")

o Func GetWorkbench( workbenchName) As

Returns one of the workbenches of the document.

Parameters:

workbenchName

The name of the workbench

Example:

This example retrieves the Structural workbench on the Doc document

 Doc.GetWorkbench("Structural")

o Func Indicate2D(		`iMessage`,
		`ioDocumentWindowLocation`) As

Runs an 2D interactive indication command.
Role: Indicate2D asks to the user to select a location in the document window. It can be used:

When this document is a DrawingDocument

When this document is a PartDocument, and a sketch is being edited ( Sketch.OpenEdition has been called and Sketch.CloseEdition has not been called yet)

See also: Selection.IndicateOrSelectElement2D which can, in particular, enable indication and not selection (positionning the iFilterType parameter to an empty string), whichs enables to subscribe to mouse move events, positionning the iTriggeringOnPreSelection to true.
Note:If the scripting language is Visual Basic for Applications or Visual Basic 6 Development Studio, then, you have to know that during the execution of an interactive selection method such as this one, no form (dialog box) must be displayed, otherwise it would lead to unpredictible results. In a form method, before calling an interactive selection method such as Document.Indicate2D, you must hide all forms, and, after the call to the method, you must show the forms.

Parameters:

iMessage: A string which instructs the user that he must select a location in the document window. This string is displayed in the message area located at the left of the power input area.
oDocumentWindowLocation: An array made of 2 doubles: X, Y - coordinates array of the location the user specified in the document window.
oOutputState: The state of the indication command once Indicate2D returns. It can be either "Normal" (the indication has succeeded), "Cancel" (the user wants to cancel the VB command, which must exit immediately, see the oOutputState parameter of the

Selection.SelectElement2 method), "Undo" or "Redo". About the use of "Undo" and "Redo", see the example of the Selection.SelectElement2 method.

Example:

The following example suppose a drawing document is currently edited. It asks the end user to select a location in the current drawing window, and creates a text (see DrawingText ) at the specified location:

 Set Document = CATIA.ActiveDocument : Set Selection = Document.Selection : Set DrawingSheets  = Document.Sheets 
 Set DrawingSheet = DrawingSheets.ActiveSheet : Set DrawingViews = DrawingSheet.Views
 Set DrawingView = DrawingViews.ActiveView : Set DrawingTexts = DrawingView.Texts
 'We propose to the user that he specify a location in the drawing window
 Dim DrawingWindowLocation(1)
 Status=Document.Indicate2D("select a location into the drawing window",DrawingWindowLocation)
 if (Status = "Cancel") then Exit Sub
 Set DrawingText=DrawingTexts.Add("Hello world",DrawingWindowLocation(0),DrawingWindowLocation(1))

o Func Indicate3D(		`iPlanarGeometricObject`,
		`iMessage`,
		`ioWindowLocation2D`,
		`ioWindowLocation3D`) As

Runs an 3D interactive indication command.
Role: Indicate3D asks to the user to select a location in the document window. It cannot be used:

When this document is a DrawingDocument

When this document is a PartDocument, and a sketch is being edited ( Sketch.OpenEdition has been called and Sketch.CloseEdition has not been called yet)

In these cases, Indicate2D must be used.
See also: Selection.IndicateOrSelectElement3D which can, in particular, enable indication and not selection (positionning the iFilterType parameter to an empty string), whichs enables to subscribe to mouse move events, positionning the iTriggeringOnPreSelection to true.
Note:If the scripting language is Visual Basic for Applications or Visual Basic 6 Development Studio, then, you have to know that during the execution of an interactive selection method such as this one, no form (dialog box) must be displayed, otherwise it would lead to unpredictible results. In a form method, before calling an interactive selection method such as Document.Indicate2D, you must hide all forms, and, after the call to the method, you must show the forms.

Parameters:

iPlanarGeometricObject: A planar geometric object.
The following objects are supported:

HybridShapeCircle, HybridShapeCircleExplicit, HybridShapeConic, Sketch, Circle2D, Ellipse2D, Hyperbola2D, Parabola2D and Spline2D.

iMessage

A string which instructs the user that he must select a location in the document window. This string is displayed in the message area located at the left of the power input area.

oWindowLocation2D

An array made of 2 doubles: X, Y - coordinates array of the location the user specified in the document window, in the input planar object coordinates system

oWindowLocation3D

An array made of 3 doubles: X, Y, Z - coordinates array of the location the user specified in the document window

oOutputState

The state of the indication command once Indicate3D returns. It can be either "Normal" (the indication has succeeded), "Cancel" (the user wants to cancel the VB command, which must exit immediately, see the oOutputState parameter of the

Example:

Selection.SelectElement2Selection.SelectElement2 The following example asks the end user to select a location in the document window, on the Plane.1 plane, and creates a HybridShapePointOnPlane at the specified location:

 Set Document = CATIA.ActiveDocument : Set Part  = Document.Part : Set Selection = Document.Selection
 Set HybridShapeFactory = Part.HybridShapeFactory
 Set HybridShapePlane = Part.Bodies.Item("PartBody").HybridShapes.Item("Plane.1")
 Set PlaneReference = Part.CreateReferenceFromObject(HybridShapePlane)
 'We propose to the user that he select a location in the window
 ReDim WindowLocation2D(1),WindowLocation3D(2)
 Status=Document.Indicate3D(HybridShapePlane,"select a location in the document window", _ 
                             WindowLocation2D,WindowLocation3D)
 if (Status = "Cancel") then Exit Sub
 Set HybridShapePointOnPlane = HybridShapeFactory.AddNewPointOnPlane( _
                                 PlaneReference,WindowLocation2D(0),WindowLocation2D(1))
 Part.Bodies.Item("PartBody").InsertHybridShape HybridShapePointOnPlane
 Part.InWorkObject = HybridShapePointOnPlane
 Part.Update

o Func NewWindow(

) As

Activates the window which contains the document and duplicates this window. This implies creating a window, displaying the active document in this window with the same view point, making this window the active one, and adding the window to the collection of windows.

Example:

This example creates the MyWindow new window for the Doc document.

 Dim MyWindow As Window
 Set MyWindow = Doc.NewWindow()

Example:

The second example below shows a functionality that cannot be carried out interactively. An already loaded, but non active, document is retrieved from the collection of documents and is used to create the new window MyWindow. This window does not display the PartDocument MyPart used to call the NewWindow method. It is a duplication of the active window displaying the active document.

 Sub CATMain()
   Dim MyPart As PartDocument
   Set MyPart = CATIA.Documents.Item("Part1.CATPart")
   Dim MyWindow As Window
   Set MyWindow = MyPart.NewWindow()
 End Sub

o Sub RemoveFilter( iFilterName)

Removes an existing visualization filter. Fails if the filter to be removed is the current filter.

Parameters:

iFilterName

The filter name.

Example:

This example removes the filter named "Filter001" for the Doc document.