TreeView Interface

An editable view of a (version control style) branch of a shared tree based on some schema.

This schema--known as the view schema--may or may not align the stored schema of the document. Information about discrepancies between the two schemas is available via compatibility.

Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and choose a schema compatibility policy that aligns with their application's needs.

Signature

/** @sealed */
export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable

Extends: IDisposable

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Properties

Property	Modifiers	Type	Description
compatibility	readonly	SchemaCompatibilityStatus	Description of the current compatibility status between the view schema and stored schema. schemaChanged() is fired when the compatibility status changes.
events	readonly	Listenable<TreeViewEvents>	Events for the tree.
root		TreeFieldFromImplicitField<TSchema>	The current root of the tree. If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility's canView before using. To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback). To get notified about changes to stored schema (which may affect compatibility between this view's schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).
schema	readonly	TSchema	The view schema used by this TreeView.

Methods

Method	Return Type	Description
initialize(content)	void	Initialize the tree, setting the stored schema to match this view's schema and setting the tree content. Only valid to call when this view's canInitialize is true. Applications should typically call this function before attaching a SharedTree.
upgradeSchema()	void	When the schemas are not an exact match and canUpgrade is true, this can be used to modify the stored schema to make it match the view schema. This will update the compatibility state, and allow access to root. Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!

Property Details

compatibility

Description of the current compatibility status between the view schema and stored schema.

schemaChanged() is fired when the compatibility status changes.

Signature

readonly compatibility: SchemaCompatibilityStatus;

Type: SchemaCompatibilityStatus

events

Events for the tree.

Signature

readonly events: Listenable<TreeViewEvents>;

Type: Listenable<TreeViewEvents>

root

The current root of the tree.

If the view schema not sufficiently compatible with the stored schema, accessing this will throw. To handle this case, check compatibility's canView before using.

To get notified about changes to this field, use rootChanged() via view.events.on("rootChanged", callback).

To get notified about changes to stored schema (which may affect compatibility between this view's schema and the stored schema), use schemaChanged() via view.events.on("schemaChanged", callback).

Signature

get root(): TreeFieldFromImplicitField<TSchema>;
set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);

Type: TreeFieldFromImplicitField<TSchema>

schema

The view schema used by this TreeView.

Signature

readonly schema: TSchema;

Type: TSchema

Method Details

initialize

Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.

Only valid to call when this view's canInitialize is true.

Applications should typically call this function before attaching a SharedTree.

Signature

initialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;

Parameters

Parameter	Type	Description
content	InsertableTreeFieldFromImplicitField<TSchema>	The content to initialize the tree with.

upgradeSchema

When the schemas are not an exact match and canUpgrade is true, this can be used to modify the stored schema to make it match the view schema. This will update the compatibility state, and allow access to root. Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!

Signature

upgradeSchema(): void;

Remarks

It is an error to call this when canUpgrade is false, and a no-op when the stored and view schema are already an exact match.