acrobat.collection.ICollection (ActionScript 3.0)

	Property	Defined By
		decorateFields : Boolean A PDF document can have schema fields with generic metadata types like text, date, or number.	ICollection
		fields : Array An ordered array of IField instances.	ICollection
		fileName : String [read-only] The file name of the collection, not including the path.	ICollection
		items : IList [read-only] An ordered list of non-null IAttachment instances.	ICollection
		locale : String [read-only] Gets the locale for this collection's resources.	ICollection
		permissions : IPermissions [read-only] Represents the set of permissions for this collection.	ICollection
		sort : Array An ordered array of ISort instances.	ICollection
		thumbnail : Bitmap [read-only] A thumbnail representing the attachment.	ICollection

	Method	Defined By
		addFiles(response:Function = null):void Launches a file import dialog for the purpose of importing a file or group of files from the host file system to the package.	ICollection
		addFolder(response:Function = null):void Launches a folder import dialog for the purpose of recursively importing a folder structure from the host file system into the package.	ICollection
		addResource(browseDialogTitle:String, browseDialogFilters:Array, relativeURL:String, response:Function = null):void Adds custom resources needed by the navigators.	ICollection
		createFolder(name:String, response:Function = null):void Create a new folder in the current folder.	ICollection
		deleteItems(attachments:Array, response:Function = null):void Deletes the specified attachments.	ICollection
		deleteResource(relativeURL:String, response:Function = null):void Deletes the resource associated with the path.	ICollection
		getLocalizedString(key:String, defaultValue:String = null):String Gets a localized string from the navigator's resources contained in the collection.	ICollection
		requestThumbnail(maxWidth:int, maxHeight:int):void Behaves the same as IAttachment.requestThumbnail(), except that the thumbnail represents the collection rather than an individual attachment.	ICollection
		setDirty():void Sets the flag indicating that the ICollection is dirty and needs to be saved.	ICollection
		writeResource(buffer:ByteArray, relativeURL:String, response:Function = null):void Replaces the contents of the navigator custom resource if one exists for the given path or creates a new one otherwise.	ICollection

	Event	Summary	Defined By
		needsSave	Dispatched when pending data should be written out.	ICollection

Property Detail

decorateFields

property

decorateFields:Boolean [read-write]

Player Version :

Acrobat ActionScript API 9.0

A PDF document can have schema fields with generic metadata types like text, date, or number. An ICollection schema always includes these fields; additionally, it can have schema fields that map to properties of an embedded file, such as the file's name, creation date, modified date, etc.

When the decorateFieldsproperty is true, the following set of IField instances is included in the collection's fields property, in the given order:

Name	Type	Editable	Visible
"FileName"	FieldType.FILE_NAME	`true`	`true`
"Description"	FieldType.DESCRIPTION	`true`	`true`
"ModDate"	FieldType.MOD_DATE	`false`	`true`
"Size"	FieldType.SIZE	`false`	`true`
"CompressedSize"	FieldType.COMPRESSED_SIZE	`false`	`true`
"CreationDate"	FieldType.CREATION_DATE	`false`	`false`

The displayName for each field varies with Acrobat's current runtime locale. When this property is false and the navigator sets it to true, the standard fields are prepended to any fields that already exist. All of these standard fields map to attachment properties whose values are always stored in the PDF document, regardless of the document's collection schema. When this property is set to true, Acrobat does not permanently add these fields to the PDF document's schema. The document is not dirtied.

The default value is true.

This property can be used as the source for data binding.

Implementation
public function get decorateFields():Boolean
public function set decorateFields(value:Boolean):void

See also

IField

fields

property

fields:Array [read-write]

Player Version :

Acrobat ActionScript API 9.0

An ordered array of IField instances.

The description for this API sometimes refers to the fields property as the "schema fields" or "schema" of the ICollection.

The array may be empty but can never be null.

This property may only be set when the permission "Document"/"Modify" has been granted.

The returned array is always a copy of the array contained by the ICollection instances. Modifications to this array copy have no effect on the ICollection.

There are restrictions on the array when setting this property:

The array can only contain IField instances that were returned by a previous get of this property. (In other words, callers cannot create their own IField implementations.)
Fields cannot be added to or removed from the schema using this call. Consequently the array must have exactly one field with the same name as each existing field.

Typical usage is to get the existing fields array, optionally rearrange the entries, optionally modify IField instances by calling setters, and set the property to this modified array.

This property can be used as the source for data binding.

Implementation
public function get fields():Array
public function set fields(value:Array):void

Throws

Error — An Error is thrown if the array violates any of the rules described above.

fileName

property

fileName:String [read-only]

Player Version :

Acrobat ActionScript API 9.0

The file name of the collection, not including the path.

This property can be used as the source for data binding.

Implementation
public function get fileName():String

items

property

items:IList [read-only]

Player Version :

Acrobat ActionScript API 9.0

An ordered list of non-null IAttachment instances.

The IList may be empty but will never be null. The IList is read-only; attempts to modify it will generate exceptions.

Implementation
public function get items():IList

See also

IAttachment
mx.collections.IList

locale

property

locale:String [read-only]

Player Version :

Acrobat ActionScript API 9.0

Gets the locale for this collection's resources.

The locale is given as an ISO language and region code. For example, "en_US".

Implementation
public function get locale():String

permissions

property

permissions:IPermissions [read-only]

Player Version :

Acrobat ActionScript API 9.0

Represents the set of permissions for this collection.

If a function or read-write property in this interface has a dependency on the permissions property, it is explicitly noted in the description of that function or property. An Error is thrown while calling any function or setting any read-write property when the value of permissions disallows it.

This property can be used as the source for data binding.

Implementation
public function get permissions():IPermissions

sort

property

sort:Array [read-write]

Player Version :

Acrobat ActionScript API 9.0

An ordered array of ISort instances. Lower-indexed records are higher in sort priority. The INavigatorHost instance's getter always returns a copy.

When changing the sort order, the INavigator implementation is free to reuse existing ISort instances, or create new ones.

When the sort order changes, it may invalidate Acrobat's current settings for the next and previous IAttachment instances. If so, the INavigator instance must notify the INavigatorHost by calling INavigatorHost.setNextPrevious().

This property may only be set when the permission "Document"/"Modify" has been granted.

This property can be used as the source for data binding.

Implementation
public function get sort():Array
public function set sort(value:Array):void

Throws

Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

thumbnail

property

thumbnail:Bitmap [read-only]

Player Version :

Acrobat ActionScript API 9.0

A thumbnail representing the attachment.

By default, the value is a cached image from the collection. The requestThumbnail function can be called to request a thumbnail with particular dimensions.

This property can be used as the source for data binding.

Implementation
public function get thumbnail():Bitmap

Method Detail

addFiles

()

method

public function addFiles(response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Launches a file import dialog for the purpose of importing a file or group of files from the host file system to the package. Files are added to the current folder.

This operation is only allowed when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have been granted.

The method accepts an optional callback function as an argument. The callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void

The response:Object parameter contains properties that define the response. These include:

Property	Type	Value
`success`	`Boolean`	`true` if the operation succeeded; `false` otherwise

Parameters

response:Function (default = null) — Optional notification function, as described above.

Throws

Error — Throws an Error if called when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have not been granted.

See also

ICollection.permissions
Object

addFolder

()

method

public function addFolder(response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Launches a folder import dialog for the purpose of recursively importing a folder structure from the host file system into the package. The new folder structure is added to the current folder. All files and folders are added to the package with the same name they have in the file system.

This operation is only allowed when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have been granted.

    function callback(response:Object):void

The response:Object parameter contains properties that define the response. These include:

Property	Type	Value
`success`	`Boolean`	`true` if the operation succeeded; `false` otherwise.

Parameters

response:Function (default = null) — Optional notification function, as described above.

Throws

Error — Throws an Error if called when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have not been granted.

See also

ICollection.permissions
Object

addResource

()

method

 public function addResource(browseDialogTitle:String, browseDialogFilters:Array, relativeURL:String, response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Adds custom resources needed by the navigators. It brings up a file browsing dialog prompting the user to select the needed file. Types that are not blacklisted will be added to the resources.

The data can later be accessed by any call that can read data from a URL.

This operation is only allowed when the permission "Document"/"Modify" has been granted.

It accepts an optional callback function as an argument. When it is non-null, the callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void

The response:Object parameter contains properties that describe the response. These include:

Property	Type	Value
`"success"`	`Boolean`	`true` if the operation succeeded; `false` otherwise
`"relativeURL"`	`String`	The path that identifes the resource. This is the full relative path to the resource, and may differ from `originalURL` if the caller passes an incomplete path, which is then completed by addResource().
`"originalURL"`	`String`	The path under which this resource was requested. It will match `relativeURL` except in the case where `addResource()` has completed an incomplete URL.
`"error"`	`String`	A non-human-readable String describing the error. It is non-`null` only if `success` is `false`.

Parameters

	`browseDialogTitle:String` — The title of the File browse dialog. This is prefixed by a string to indicate to the user that this is coming from the navigator.

	`browseDialogFilters:Array` — An `Array` of `FileFilter` objects and will be used in the File browse dialog.

	`relativeURL:String` — The path where the resource will be added. It must be a relative path, "/" separated, but with no leading "/". If the URL does not have a file extension (that is, it does not contain a '.'), then the file extension of the added file (if any) will be appended. If the URL ends with "/", then the entire file name of the selected file will be appended.

	`response:Function` (default = `null`) — An optional notification function, as described above.

Throws

Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

createFolder

()

method

public function createFolder(name:String, response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Create a new folder in the current folder.

This operation is only allowed when the permission "EmbeddedFile"/"Create" has been granted.

    function callback(response:Object):void

The response:Object parameter contains properties that define the response. These include:

Property	Type	Value
`success`	`Boolean`	`true` if the operation succeeded; `false` otherwise.

Parameters

	`name:String` — The folder name. The value `null` tells the framework to choose a default name.

	`response:Function` (default = `null`) — An optional notification function, as described above.

Throws

Error — Throws an Error if called when the permission "EmbeddedFile"/"Create" has not been granted.

See also

ICollection.permissions
Object

deleteItems

()

method

public function deleteItems(attachments:Array, response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Deletes the specified attachments.

If any of the attachments are in the current selection, the host will remove them from the selection (and generate the appropriate notification).

This operation is only allowed when the permission "EmbeddedFile"/"Delete" has been granted

    function callback(response:Object):void

The response:Object parameter contains properties that define the response. These include:

Property	Type	Value
`success`	`Boolean`	`true` if the operation succeeded; `false` otherwise.

Parameters

	`attachments:Array` — An `Array` of attachments to delete. Each element is an `IAttachment` instance. If an element in the array is a folder, then that folder and all its children will be deleted.

	`response:Function` (default = `null`) — An optional notification function, as described above.

Throws

Error — Throws an Error if called when the permission "EmbeddedFile"/"Delete" has not been granted.

See also

Object
Array
IAttachment

deleteResource

()

method

public function deleteResource(relativeURL:String, response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Deletes the resource associated with the path.

This operation is only allowed when the permission "Document"/"Modify" has been granted.

Accepts an optional callback function as an argument. When it is non-null, the callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void

The response:Object parameter contains properties that describe the response. These include:

Property	Type	Value
`"success"`	`Boolean`	`true` if the operation succeeded; `false` otherwise.
`"error"`	`String`	A non-human-readable String describing the error. It is non-`null` only if `success` is `false`.
`"relativeURL"`	`String`	The value of the `relativeURL` parameter in the function call.

Parameters

	`relativeURL:String` — The path to the resource to be deleted. It must match a path used previously on a successful call to `addResource()` or `writeResource()`.

	`response:Function` (default = `null`) — An optional notification function, as described above.

Throws

Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

getLocalizedString

()

method

public function getLocalizedString(key:String, defaultValue:String = null):String

Player Version :

Acrobat ActionScript API 9.0

Gets a localized string from the navigator's resources contained in the collection.

Adobe provides support for including sets of localized strings in a navigator's .nav file. See the navigator file format documentation for more details.

Parameters

	`key:String` — A unique key identifying a localized string.

	`defaultValue:String` (default = `null`) — A default value for the localized string.

Returns

String — The string identified by key, localized for the collection's locale. If the collection does not contain such a string, and a non-null defaultValue argument has been specified, defaultValue is returned; if defaultValue was not specified, an empty string is returned.

requestThumbnail

()

method

public function requestThumbnail(maxWidth:int, maxHeight:int):void

Player Version :

Acrobat ActionScript API 9.0

Behaves the same as IAttachment.requestThumbnail(), except that the thumbnail represents the collection rather than an individual attachment.

Parameters

	`maxWidth:int`

	`maxHeight:int`

See also

IAttachment.requestThumbnail()

setDirty

()

method

public function setDirty():void

Player Version :

Acrobat ActionScript API 9.0

Sets the flag indicating that the ICollection is dirty and needs to be saved. This enables the Save option in the File menu.

writeResource

()

method

public function writeResource(buffer:ByteArray, relativeURL:String, response:Function = null):void

Player Version :

Acrobat ActionScript API 9.0

Replaces the contents of the navigator custom resource if one exists for the given path or creates a new one otherwise.

This operation is only allowed when the permission "Document"/"Modify" has been granted.

    function callback(response:Object):void

The response:Object parameter contains properties that describe the response. These include:

Property	Type	Value
`"success"`	`Boolean`	`true` if the operation succeeded; `false` otherwise.
`"overwrite"`	`Boolean`	`true` if the operation resulted in an existing resource being overwritten; `false` otherwise.
`"error"`	`String`	A non-human-readable String describing the error. It is non-`null` only if `success` is `false`.
`"relativeURL"`	`String`	The value of the `relativeURL` parameter in the function call.

Parameters

	`buffer:ByteArray` — The byte array that contains the buffer that will be written to the file.

	`relativeURL:String` — The path where the resource will be added/replaced. It must be a relative path, "/" separated, but with no leading "/".

	`response:Function` (default = `null`) — An optional notification function, as described above.

Throws

Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

Event Detail

needsSave

Event

Event Object Type: flash.events.Event
Event.type property = mx.events.FlexEvent.APPLICATION_COMPLETE

Player Version :

Acrobat ActionScript API 9.0

Dispatched when pending data should be written out.

The FlexEvent.APPLICATION_COMPLETE constant defines the value of the type property of the event object for a applicationComplete event.

The properties of the event object have the following values:

Property	Value
`bubbles`	false
`cancelable`	false
`currentTarget`	The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`target`	The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.

Submit Feedback on LiveDocs

Current page: http://livedocs.adobe.com/navigator/9/Navigator_SDK9_HTMLHelp/API_References/Acrobat_Navigator_API_Reference/acrobat/collection/ICollection.html

Acrobat ActionScript API Reference	All Packages \| All Classes \| Index \| Conventions \| Frames No Frames
ICollection	Properties \| Methods \| Events \| Styles \| Effects \| Constants \| Examples

Package	acrobat.collection
Interface	public interface ICollection extends IEventDispatcher