IDocuments

class IDocuments

Bases: ImpactCOMWrapperBase, Iterable

Description:

A collection of IDocument objects

Remarks:

The IDocuments collection may support paging of documents if the underlying document provider supports paging. See the IDocumentContext object for information about paging using IDocuments.

Wraps a COM object or another wrapper instance. Accepts: - A valid impact_object - An existing impact_com_wrapper_base-derived instance

property auto_relationship

Gets auto_relationship.

Description:

Determines the type of document relationship that will be created when adding documents using this IDocuments collection.

Remarks:

When adding documents using an IDocuments collection retrieved from an existing Impact object each IDocument will automatically have a relationship to that object created as well. For example an IDocuments collection retrieved from the ICustomer.documents property will automatically have a document relationship created that references the ICustomer. By default a relationship is created for the latest version of the document series (darLatestVersion). However you can change this behaviour by setting auto_relationship to darNone or darCurrentVersion. Introduced in Impact 9.0.0.83.

Returns:

The value of auto_relationship.

Return type:

auto_relationship (ipDocumentAutoRelationship)

property count

Gets Count.

Description:

The number of items in this collection.

Remarks:

When using_paging is true the Count property returns the number of items for the current page. The total_count property will return the total number of documents for all pages.

Returns:

The value of Count.

Return type:

count (int)

property creator

Gets Creator.

Description:

Retrieves an IDocumentCreator object for adding multiple documents in one operation.

Remarks:

Introduced in Impact 9.0.0.83.

Returns:

The value of Creator.

Return type:

creator (IDocumentCreator)

property page_count

Gets page_count.

Description:

The number of pages of documents.

Remarks:

You should only use this property when using_paging is true. See using_paging for more details. Introduced in Impact 9.0.0.83.

Returns:

The value of page_count.

Return type:

page_count (int)

property page_number

Gets page_number.

Description:

The current page number.

Remarks:

You should only use this property when using_paging is true. Page numbers start at 1 to page_size inclusive. See using_paging for more details. Introduced in Impact 9.0.0.83.

Returns:

The value of page_number.

Return type:

page_number (int)

property page_size

Gets page_size.

Description:

The number of documents per page.

Remarks:

You should only use this property when using_paging is true. See using_paging for more details. Introduced in Impact 9.0.0.83.

Returns:

The value of page_size.

Return type:

page_size (int)

property relationship_count

Gets relationship_count.

Description:

The number of unique relationships for documents in this collection.

Remarks:

See the Relationship method for details. Introduced in Impact 9.0.0.83.

Returns:

The value of relationship_count.

Return type:

relationship_count (int)

property total_count

Gets total_count.

Description:

Determines the total number of items in the collection when using paging.

Remarks:

You should only use this property when using_paging is true. The total_count property will return the total number of documents for all pages. The Count property will return the number of items for the current page. See using_paging for more details. Introduced in Impact 9.0.0.83.

Returns:

The value of total_count.

Return type:

total_count (int)

property using_paging

Gets using_paging.

Description:

Determines if the IDocuments collection supports paging.

Remarks:

The IDocuments collection may support paging of documents if the underlying document provider supports paging. See the IDocumentContext object for information about paging using IDocuments. When retrieving IDocuments for an existing Impact object such as a project, template, symbol, layer, customer, contact, user or site using_paging is always false. This is to ensure that the relationship_count property and Relationship method work as expected. Use the IDocumentContext before creating the IDocuments object to provide initialisation values. Once the IDocuments object has been created you can change the page_number property to scroll between pages, or the page_size property to change the number of items per page. To change the sort order or IDocument status values included in the collection use the IDocumentContext and the Refresh method. Introduced in Impact 9.0.0.83.

Returns:

The value of using_paging.

Return type:

using_paging (bool)

Examples:

add(file_name, comments)
Description:

Adds a document to the Document Repository from a file.

Remarks:

This method has been deprecated you should use Add2 instead. In versions prior to Impact 2015 the Comments parameter was assigned to the dkcDescription column.

Parameters:

  • file_name (str) – Full path to the document file to add to the repository.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add2(file_name, values, initial_version, comments)
Description:

Adds a document to the Document Repository from a file.

Remarks:

The file_name does not have to be unique and multiple documents with the same name can be added. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the file_name parameter based on the file extension. The Values parameter is optional and if not provided the dkcName will be inferred from the file_name parameter. Use the Values parameter to provide values for any document columns that you want to be assigned when the document is added to the document repository. You can also override the dkcType and dkcGroup if required. Check supports_major_and_minor_versions to determine if using dvMinor for the initial_version is appropriate. Introduced in Impact 9.0.0.83.

Parameters:

  • file_name (str) – Full path to the document file to add to the repository.

  • values (IDatabaseValues) – An optional list of values for the document to be added.

  • initial_version (ipDocumentVersion) – Determines if the initial version is a major or minor version.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add_embedded_graphic(graphic, name, type, comments)
Description:

Adds an embedded graphic image to the Document Repository.

Remarks:

This method has been deprecated you should use add_embedded_graphic2 instead. In versions prior to Impact 2015 the Comments parameter was assigned to the dkcDescription column. This method adds the graphic image to the Documents Repository and converts the IGraphicImage so it references the new document. This method will fail if the graphic image is not an embedded image, instead use the add_graphic method. The embedded graphic image will be saved using the image format specified by Type, supported formats are ffBitmap, ffJPG, ffTIFF.

Parameters:

  • graphic (IGraphicImage) – Graphic Image to add to the repository.

  • name (str) – Name of the new document (excluding extension).

  • type (ipFileFormat) – Image type to store the graphic image as.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add_embedded_graphic2(graphic, name, type, values, initial_version, comments)
Description:

Adds an embedded graphic image to the Document Repository.

Remarks:

This method adds the graphic image to the Documents Repository and converts the IGraphicImage so it references the new document. This method will fail if the graphic image is not an embedded image, instead use the add_graphic2 method. The embedded graphic image will be saved using the image format specified by Type, supported formats are ffBitmap, ffJPG, ffTIFF. The Name does not have to be unique and multiple documents with the same name can be added. The Name will automatically have a file extension appended based on the Type parameter. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the file extension. Use the Values parameter to provide values for any document columns that you want to be assigned when the document is added to the document repository. You can also override the dkcType and dkcGroup if required. Check supports_major_and_minor_versions to determine if using dvMinor for the initial_version is appropriate. Introduced in Impact 9.0.0.83.

Parameters:

  • graphic (IGraphicImage) – Graphic Image to add to the repository.

  • name (str) – Name of the new document (excluding extension).

  • type (ipFileFormat) – Image type to store the graphic image as.

  • values (IDatabaseValues) – An optional list of values for the document to be added.

  • initial_version (ipDocumentVersion) – Determines if the initial version is a major or minor version.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add_from_stream(stream, file_name, chunk_size, comments)
Description:

Adds a document to the Document Repository from a stream.

Remarks:

This method has been deprecated you should use add_from_stream2 instead. In versions prior to Impact 2015 the Comments parameter was assigned to the dkcDescription column.

Parameters:

  • stream (win32com.client.Dispatch) – Specifies the stream to add the document from. The IUnknown interface passed here must support the IStream interface.

  • file_name (str) – Specifies the file name used to identify the document.

  • chunk_size (int) – Specifies the number of bytes to read for each sequential access to the specified stream. This value must be between 1K (1024 bytes) and 1MB (1048576 bytes), if a value is specified outside this range then the actual value used will be modified to fit into the range.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add_from_stream2(stream, file_name, chunk_size, values, initial_version, comments)
Description:

Adds a document to the Document Repository from a stream.

Remarks:

The file_name does not have to be unique and multiple documents with the same name can be added. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the file_name parameter based on the file extension. The Values parameter is optional and if not provided the dkcName will be inferred from the file_name parameter. Use the Values parameter to provide values for any document columns that you want to be assigned when the document is added to the document repository. You can also override the dkcType and dkcGroup if required. Check supports_major_and_minor_versions to determine if using dvMinor for the initial_version is appropriate. Introduced in Impact 9.0.0.83.

Parameters:

  • stream (win32com.client.Dispatch) – Specifies the stream to add the document from. The IUnknown interface passed here must support the IStream interface.

  • file_name (str) – Specifies the file name used to identify the document.

  • chunk_size (int) – Specifies the number of bytes to read for each sequential access to the specified stream. This value must be between 1K (1024 bytes) and 1MB (1048576 bytes), if a value is specified outside this range then the actual value used will be modified to fit into the range.

  • values (IDatabaseValues) – An optional list of values for the document to be added.

  • initial_version (ipDocumentVersion) – Determines if the initial version is a major or minor version.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

Examples:

add_graphic(graphic, comments)
Description:

Adds a graphic image to the Document Repository.

Remarks:

This method has been deprecated you should use add_graphic2 instead. In versions prior to Impact 2015 the Comments parameter was assigned to the dkcDescription column. This method adds the graphic image to the Documents Repository and converts the IGraphicImage so it references the new document. This method will fail if the graphic image is an embedded image, instead use the add_embedded_graphic method.

Parameters:

  • graphic (IGraphicImage) – Graphic Image to add to the repository.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

add_graphic2(graphic, values, initial_version, comments)
Description:

Adds a graphic image to the Document Repository.

Remarks:

This method adds the graphic image to the Documents Repository and converts the IGraphicImage so it references the new document. This method will fail if the graphic image is an embedded image, instead use the add_embedded_graphic method. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the IGraphicImage.file_name property based on the file extension. The Values parameter is optional and if not provided the dkcName will be inferred from the IGraphicImage.file_name property. Use the Values parameter to provide values for any document columns that you want to be assigned when the document is added to the document repository. You can also override the dkcType and dkcGroup if required. Check supports_major_and_minor_versions to determine if using dvMinor for the initial_version is appropriate. Introduced in Impact 9.0.0.83.

Parameters:

  • graphic (IGraphicImage) – Graphic Image to add to the repository.

  • values (IDatabaseValues) – An optional list of values for the document to be added.

  • initial_version (ipDocumentVersion) – Determines if the initial version is a major or minor version.

  • comments (str) – Optional comments that will added to IDocumentHistoryItem.details when the document is added.

item(index)
Description:

Gets an IDocument object with the specified name or index.

Parameters:

index (any) – Specifies the name or index of the document to retrieve.

refresh()
Description:

Refresh the collection of IDocuments directly from the document provider.

Remarks:

When using_paging you can use the IDocumentContext object and the Refresh method to apply a new sort order or the status of documents included in the collection. Introduced in Impact 9.0.0.83.

relationship(index)
Description:

Gets an IDocumentsRelationship object with the specified name or index.

Remarks:

This property returns a list of unique IDocumentsRelationship objects associated with all the documents within the collection. Normally a single IDocumentsRelationship is returned for each IDocuments collection that references the object that the collection is associated with. For example an IDocuments collection retrieved from the ICustomer.documents property will return an IDocumentsRelationship that references the ICustomer. When the IDocuments collection is retrieved from the IDatabaseItem.all_documents property the IDocuments collection may contain documents that have a relationship to the project, any project layers, the project’s customer and the project’s site. Use the Relationship property to determine each object that documents within the collection have a relationship to. Introduced in Impact 9.0.0.83.

Parameters:

index (any) – Specifies the name or index of the documents relationship to retrieve.

rowset_options(instance_i_d)
Description:

An IRowsetOptions object defining the rowset options for the specified document instance.

Remarks:

Introduced in Impact 10.0.0.67

Parameters:

instance_id (str) – The document GUID.

Examples