IMultiSelection Interface

This interface is implemented by the Multiple Selection Object. Its methods and properties are directly accessed by the low-level (native) languages like C++ and indirectly by automation-compatible languages, such as JavaScript and managed languages. Refer to Creating Multiple Selection Object and Working with Multiple Selection Object sections for usage information.

Declaration

interface IMultiSelection extends ${IDispatch} {
    // Properties
    readonly ${Count}: number;
    readonly ${Empty}: boolean;
    readonly ${TotalSize}: number;

    // Methods
    ${AddRange}(Offset: number, Size: number): void;
    ${Clear}(): void;
    ${DeleteRange}(Offset: number, Size: number): void;
    ${InsertRange}(Offset: number, Size: number): void;
    ${Invert}(Size: number): void;
    ${IsIn}(Offset: number): void;
    ${RemoveRange}(Offset: number, Size: number): void;
    ${ToggleRange}(Offset: number, Size: number): void;
}

public interface IMultiSelection : ${IDispatch}
{
    // Properties
    ulong ${Count} { get; }
    bool ${Empty} { get; }
    ulong ${TotalSize} { get; }

    // Methods
    void ${AddRange}(ulong Offset, ulong Size);
    void ${Clear}();
    void ${DeleteRange}(ulong Offset, ulong Size);
    void ${InsertRange}(ulong Offset, ulong Size);
    void ${Invert}(ulong Size);
    void ${IsIn}(ulong Offset);
    void ${Load}(IStream Stream, ${LoadMode} LoadMode);
    void ${RemoveRange}(ulong Offset, ulong Size);
    void ${Save}(IStream Stream);
    void ${ToggleRange}(ulong Offset, ulong Size);
}

struct IMultiSelection : IDispatch
{
    // Properties
    unsigned long long ${Count};  // get 
    VARIANT_BOOL ${Empty};  // get 
    unsigned long long ${TotalSize};  // get 

    // Methods
    HRESULT ${AddRange}(unsigned long long Offset, unsigned long long Size);
    HRESULT ${Clear}();
    HRESULT ${DeleteRange}(unsigned long long Offset, unsigned long long Size);
    HRESULT ${InsertRange}(unsigned long long Offset, unsigned long long Size);
    HRESULT ${Invert}(unsigned long long Size);
    HRESULT ${IsIn}(unsigned long long Offset);
    HRESULT ${Load}(IStream * Stream, ${LoadMode} LoadMode);
    HRESULT ${RemoveRange}(unsigned long long Offset, unsigned long long Size);
    HRESULT ${Save}(IStream * Stream);
    HRESULT ${ToggleRange}(unsigned long long Offset, unsigned long long Size);
};

IMultiSelection Properties

Count

readonly Count: number;

ulong Count { get; }

unsigned long long Count;  // get

Returns the number of ranges in a selection object.

Complexity: constant-time.

Using the Count property

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();
alert(msel.Count); // displays "0"
msel.AddRange(100, 20);  // selection: [100..120)
alert(msel.Count); // displays "1"
msel.AddRange(150, 20);  // selection: [100..120) U [150..170)
alert(msel.Count); // displays "2"
msel.AddRange(80, 80); // selection: [80..170)
alert(msel.Count); // displays "1"

Empty

readonly Empty: boolean;

bool Empty { get; }

VARIANT_BOOL Empty;  // get

This property is true if the selection object is empty.

Using the Empty property

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();
alert(msel.Empty); // displays "true"
msel.AddRange(100, 20);  // selection: [100..120)
alert(msel.Empty); // displays "false"
msel.Clear();
alert(msel.Empty); // displays "true"

TotalSize

readonly TotalSize: number;

ulong TotalSize { get; }

unsigned long long TotalSize;  // get

Returns the total selection size. This is a sum of sizes of all selection ranges.

Complexity: constant-time.

Using TotalSize property

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();

msel.ToggleRange(100, 50);  // selection: [100..150)
alert(msel.TotalSize); // displays "50"
msel.ToggleRange(100, 10);  // selection: [110..150)
alert(msel.TotalSize); // displays "40"
msel.ToggleRange(0, 10);  // selection: [0..10) U [110..150)
alert(msel.TotalSize); // displays "50"
msel.ToggleRange(140, 20);  // selection: [0..10) U [110..140) U [150..160)
alert(msel.TotalSize); // displays "50"
msel.ToggleRange(10, 100);  // selection: [0..140) U [150..160)
alert(msel.TotalSize); // displays "150"

IMultiSelection Methods

AddRange

AddRange(Offset: number, Size: number): void;

void AddRange(ulong Offset, ulong Size);

HRESULT AddRange(unsigned long long Offset, unsigned long long Size);

Offset: Starting offset
Size: Range size

Adds a given range to a selection. If the range intersects any existing ranges, they are combined with a given range. A number of ranges in a selection may change after adding a new range.

Complexity: linear-time, depending on the current selection configuration.

Adding ranges to a selection

// msel is initialized elsewhere and is currently empty
msel.AddRange(100, 20);  // selection: [100..120)
msel.AddRange(150, 20);  // selection: [100..120) U [150..170)
msel.AddRange(80, 80); // selection: [80..170)

Clear

Clear(): void;

void Clear();

HRESULT Clear();

Clears the selection. After this function returns, selection object contains no ranges.

Complexity: constant-time.

DeleteRange

DeleteRange(Offset: number, Size: number): void;

void DeleteRange(ulong Offset, ulong Size);

HRESULT DeleteRange(unsigned long long Offset, unsigned long long Size);

Offset: N/A
Size: N/A

This method is not currently implemented.

InsertRange

InsertRange(Offset: number, Size: number): void;

void InsertRange(ulong Offset, ulong Size);

HRESULT InsertRange(unsigned long long Offset, unsigned long long Size);

Offset: Insert offset.
Size: Insert size.

Inserts a range into the selection object. As a result of this operation, existing ranges with offsets larger than Offset are shifted forward by Size bytes.

Complexity: linear-time, depending on the number of ranges to shift.

Using the InsertRange method

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();
msel.AddRange(100, 20);  // selection: [100..120)
msel.AddRange(150, 20);  // selection: [100..120) U [150..170)
msel.InsertRange(130, 10); // selection: [100..120) U [160..180)
msel.InsertRange(0, 20); // selection: [120..140) U [180..200)

Invert

Invert(Size: number): void;

void Invert(ulong Size);

HRESULT Invert(unsigned long long Size);

Size: The total size of an object. Used to properly invert selection.

Inverts the current selection. All defined ranges become gaps and all gaps become ranges. This method accepts the total size which is usually the current file's size. Calling Invert method two times with a same Size value will leave the selection object intact.

Complexity: constant-time.

Using the Invert method

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();
msel.AddRange(100, 20);  // selection: [100..120)
msel.Invert(200); // selection: [0..100) U [120..200)
msel.Invert(200); // selection: [100..120)

IsIn

IsIn(Offset: number): void;

void IsIn(ulong Offset);

HRESULT IsIn(unsigned long long Offset);

Offset: Offset to check.

A boolean value indicating whether the given offset lies within one of the selection's ranges.

Check if the given offset lies within the selection. Returns true if the offset is inside of selection's ranges or false otherwise.

Complexity: constant-time.

Using the IsIn method

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();
msel.AddRange(100, 20);  // selection: [100..120)
alert(msel.IsIn(0));  // displays "false"
alert(msel.IsIn(100));  // displays "true"
alert(msel.IsIn(110));  // displays "true"
alert(msel.IsIn(120));  // displays "false"

Load

// This method is not available in scripting environment

void Load(IStream Stream, ${LoadMode} LoadMode);

HRESULT Load(IStream * Stream, ${LoadMode} LoadMode);

Stream: Pointer to a stream object
LoadMode: Load mode. Can be one of the values from LoadMode enumeration.

Loads the selection from a file. This method may be instructed to merge the loaded selection with a current one, using one of supported algorithms. Due to implementation details, the Load method usually tries to read more data from the stream object, than Save method wrote to it. This is not a problem if nothing is written beyond the selection's data in a stream. Otherwise, you should prepend the selection's data in a stream with a size value and adjust the stream pointer appropriately.

Complexity: linear-time, depending on current and loaded selections complexity.

Loading and Saving selection

var fdoc = new ActiveXObject("FileDocument.FileDocument");
var msel = fdoc.CreateEmptySelection();

msel.AddRange(100, 50);  // selection: [100..150)
// create a file and obtain a stream object for it
msel.Save(stream);
msel.Clear();  // selection: empty
msel.AddRange(50, 50);  // selection: [50..100)
// open a previously created selection file and obtain a stream object for it
msel.Load(stream, SelectionAdd);  // selection: [50..150)

RemoveRange

RemoveRange(Offset: number, Size: number): void;

void RemoveRange(ulong Offset, ulong Size);

HRESULT RemoveRange(unsigned long long Offset, unsigned long long Size);

Offset: Starting offset
Size: Range size

Removes a given range from the selection. The specified range is “subtracted” from any intersected selection's ranges. If it does not intersect any range, nothing happens. The number of ranges in selection object may change after this method returns.

Complexity: linear-time, depending on the current selection configuration.

Removing ranges from a selection

// msel is initialized elsewhere and is currently empty
msel.AddRange(100, 50);  // selection: [100..150)
msel.RemoveRange(100, 10);  // selection: [110..150)
msel.RemoveRange(0, 10);  // selection: [110..150) - nothing changed
msel.RemoveRange(150, 20);  // selection: [110..150) - nothing changed
msel.RemoveRange(120, 10);  // selection: [110..120) U [130..150)

Save

// This method is not available in scripting environment

void Save(IStream Stream);

HRESULT Save(IStream * Stream);

Stream: Pointer to a stream object

Compresses and saves the selection object to a given stream.

Complexity: linear-time, depending on number of ranges in a selection object.

ToggleRange

ToggleRange(Offset: number, Size: number): void;

void ToggleRange(ulong Offset, ulong Size);

HRESULT ToggleRange(unsigned long long Offset, unsigned long long Size);

Offset: Starting offset.
Size: Range size.

Current selection ranges are intersected with a specified range. Those portions of the specified range that fall onto gaps are appended to the selection, and those portions that fall to existing ranges, are subtracted from the selection.

Complexity: linear-time, depending on the current selection configuration.

Complexity of this method is not worse than that of IMultiSelection.AddRange and IMultiSelection.RemoveRange.

Using ToggleRange method

// msel is initialized elsewhere and is currently empty
msel.ToggleRange(100, 50);  // selection: [100..150)
msel.ToggleRange(100, 10);  // selection: [110..150)
msel.ToggleRange(0, 10);  // selection: [0..10) U [110..150)
msel.ToggleRange(140, 20);  // selection: [0..10) U [110..140) U [150..160)
msel.ToggleRange(10, 100);  // selection: [0..140) U [150..160)

LoadMode