This event is dispatched when session data changes.
ICollection
Property Detail
decorateFields
property
decorateFields:Boolean
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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
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.
Represents the set of permissions for this portfolio.
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
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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.
public function addFiles(response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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.
public function addFolder(response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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.
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.
public function addResource(browseDialogTitle:String, browseDialogFilters:Array, relativeURL:String, response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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 calling loadURL().
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 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().
Use this url to later read the resource.
'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.
Can URLs have "/../" in them? If so, what happens if a URL tries to peek outside the navigator space,
for example navigator/a/b/c/../../../../header?
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. Must begin with "navigator/".
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.
public function createFolder(name:String, response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Create a new folder in the current folder.
This operation is only allowed when the permission
"EmbeddedFile"/"Create" has 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
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.
public function deleteItems(attachments:Array, response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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
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
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.
public function deleteResource(relativeURL:String, response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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 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.
Returns the 'dirty' status of the ICollection. A value of
true means that the containing portfolio document has
changes that need to be saved.
The portfolio document may be dirty either because of an explicit call
to setDirty() or as a result of the user performing
some other dirtying operation on it.
The result is returned asynchronously. The single argument is a callback
function that receives the result. Its signature is as follows:
function callback(isDirty:Boolean):void
Parameters
response:Function
getLocalizedString
()
method
public function getLocalizedString(key:String, defaultValue:String = null):String
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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-nulldefaultValue argument has
been specified, defaultValue is returned; if
defaultValue was not specified, an empty string is
returned.
getSessionData
()
method
public function getSessionData(key:String, callback:Function):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Returns session data for the specified key.
The session data is returned via a callback function. The callback
function has the following signature:
function (key:String, sessionData:*):void
where sessionData is the requested data (or 'null' if it could not be returned).
The callback function will be called exactly once. This will occur
outside the scope of the getSessionData() call.
Parameters
key:String — Key to get the state for.
callback:Function — Callback function as described above.
getSessionDataKeys
()
method
public function getSessionDataKeys(callback:Function):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Returns keys for all session data associated with this collection.
The session data keys are returned via a callback function. The
callback function has the following signature:
function (keys:Array):void
where keys is an Array of String keys.
The callback function will be called exactly once. This will occur
outside the scope of the getSessionData() call.
Parameters
callback:Function — Callback function as described above.
registerFonts
()
method
public function registerFonts(fonts:Array):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Registers an array of fonts that should be embedded by the host application. Calls to this function
are not cumulative; subsequent calls will replace the list of fonts to be embedded, rather than add
to it.
Fonts are specified as generic objects with the following properties:
Property
Type
Value
fontName
String
The name of the font family to be embedded
fontWeight
String
"bold" if the bold variant of the font should be embedded; "normal" otherwise.
fontPosture
String
"italic" if the italic variant of the font should be embedded; "normal" otherwise.
psName
String
If present, look up the font by "PostScript" name rather than using by name/weight/posture.
public function reorderFiles(attachments:Array):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Changes the order of a set of IAttachments. The new order will match
the order of the IAttachments in the array.
The attachments array should contain all the attachments for one particular
folder. Behavior when this is not the case is undefined.
Parameters
attachments:Array — Array of IAttachment instances.
resolvePath
()
method
public function resolvePath(relativeURL:String):String
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Given a relative path to a resource, return a URL from which the resource
can be loaded. Does not check for existence of the data at the URL.
Sample usage:
var url:String = collection.resolvePath("navigator/resourceData.xml");
var request:URLRequest = new URLRequest(url);
var loader:URLLoader = new URLLoader();
loader.addEventListener(Event.COMPLETE, dataLoaded);
loader.load(request);
If the relative path is not resolved to a URL in this fashion, then
the player will assume the path is relative to the application.
In some environments (such as when running in Acrobat or Reader),
this will work. In others it will not, meaning that reading data in
this way will fail.
Parameters
relativeURL:String — Relative path to resolve, with no leading "/".
Sets the flag indicating that the ICollection is dirty and needs to be saved.
This enables the Save option in the File menu.
setSessionData
()
method
public function setSessionData(key:String, sessionData:*):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 10.0
Runtime Versions :
Flash Player 10.1, AIR 2.0
Stores session data under the specified key. If any data already
exists for that key it will be deleted.
The session data must be Boolean, Number or String. Alternatively
can be null, which causes the key, if it exists, to be deleted along
with its data. Deleting a non-existent key is benign.
The following values are illegal and are not accepted:
Type
Illegal Values
Number
NaN, NEGATIVE_INFINITY, POSITIVE_INFINITY
String
empty String (length == 0),leading or trailing whitespaces
Parameters
key:String — Key under which to save the data. Must be non-null.
sessionData:* — The data to store. A null value causes the key and its data to be deleted.
writeResource
()
method
public function writeResource(buffer:ByteArray, relativeURL:String, response:Function = null):void
Language Version :
ActionScript 3.0
Product Version :
Portfolio 9.0
Runtime Versions :
Flash Player 10.1, AIR 2.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.
The maximum length of the ByteArray accepted by this method is 1,048,576 bytes.
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 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.