Class SnapServer

Represents a connection to an Snap Server instance that can be used to control interactions with the server.

Constructors

constructor

new SnapServer(server_id): SnapServer
Constructs a new instance of the Snap client object ready to connect to the given instance id

This should match the id of the server instance that is running which is the default case when using the Snap Server API, SnapServer.start
Parameters
- server_id: string
  The instance of the server that will be started or connected to
Returns SnapServer
Example
```
const server = new Snap.SnapServer('test');
```

Properties

__extensions

__extensions: SnapExtension[] = []

`Optional`client

client?: ChannelClient

emitter

emitter: EventEmitter<DefaultEventMap> = ...

`Optional`needToResetLayout

needToResetLayout?: boolean

server_id

server_id: string

The instance of the server that will be started or connected to

`Optional`snap_identity

snap_identity?: Identity_4

Methods

addEventListener

addEventListener<TEventName>(eventName, handler): void
Adds an event handler for the given event
Type Parameters
- TEventName extends
      | "all-events"
      | "client-registered"
      | "client-unregistered"
      | "move-size-completed"
      | "clients-attached"
      | "client-detached"
      | "groups-changed"
      | "client-activated"
      | "client-deactivated"
Parameters
- eventName: TEventName
  The name of the event to listen for SnapServerEventTypes
- handler: ((...eventArg: SnapServerEventTypes[TEventName]) => void)
  The handler to call when the event is fired
  - - (...eventArg): void
    - Parameters
      Rest...eventArg: SnapServerEventTypes[TEventName]
      Returns void
Returns void
void

See
SnapServerEventTypes

applySnapshot

applySnapshot(snapshot): Promise<void>

Given a snapshot, extracts the Snap layout, if any, and applies it to the current Snap Server

Parameters

snapshot: SnapSnapshot
The OpenFin.Snapshot to apply

Returns Promise<void>

Example

This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout

  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
          async applySnapshot(...args: [OpenFin.ApplySnapshotPayload, OpenFin.ClientIdentity]): Promise<void> {
           await SnapServer.prepareToApplySnapshot();
           await super.applySnapshot(...args);
           await SnapServer.applySnapshot(args[0].snapshot);
         }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});

attachWindows

attachWindows(targetClientId, toAttachClientId, targetSide, offset): Promise<void>
Attaches two windows together on a specified side and at a specified offset
Parameters
- targetClientId: string
  The client id of the window to attach to
- toAttachClientId: string
  The client id of the window to attach
- targetSide: AttachSide
  The side of the target window to attach to
- offset: number
  The offset from the target window side to attach to
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there are two windows with the client ids 'my-client-id-1' and 'my-client-id-2'
await server.attachWindows('my-client-id-1', 'my-client-id-2', 'left', 0);
```

connect

connect(): Promise<void>
Connects to an already running Snap Server instance

Use this if the Snap server has been manually started or when wanting to interact with Snap from another part of an application. For example the Snap server was started as part of a platform provider and a view would like to also interact with Snap.

Returns Promise<void>
Promise
Example
Shows how to connect to an already running Snap Server instance with the id 'test'
```
const server = new Snap.SnapServer('test');
await server.connect();
```

decorateSnapshot

decorateSnapshot(snapshot): Promise<SnapSnapshot>

Given a snapshot, decorates it with the current Snap layout and returns it

Parameters

snapshot: Snapshot
The OpenFin.Snapshot to decorate

Returns Promise<SnapSnapshot>

A Promise resolving to an instance of SnapSnapshot which contains both the original snapshot and the Snap layout

Example

This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout

  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
          async applySnapshot(...args: [OpenFin.ApplySnapshotPayload, OpenFin.ClientIdentity]): Promise<void> {
           await SnapServer.prepareToApplySnapshot();
           await super.applySnapshot(...args);
           await SnapServer.applySnapshot(args[0].snapshot);
         }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});

detachFromGroup

detachFromGroup(clientId): Promise<void>

Detaches the given window from any other windows it is attached to

Parameters

clientId: string
The client id of the window to detach

Returns Promise<void>

Promise

Example

const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
await server.detachFromGroup('my-client-id');

enableAutoWindowRegistration

enableAutoWindowRegistration(): Promise<(() => Promise<void>)>

Listens for new windows being created within the platform automatically registers them with the Snap Server

Returns Promise<(() => Promise<void>)>

A function that can be called to stop listening for new windows

Example

Setup for automatic registration of new windows and creates a new window

const server = new Snap.SnapServer('test');
await server.connect();
server.enableAutoWindowRegistration();

// The following new Window will automatically be registered with Snap
const newView = await fin.Platform.wrapSync(fin.Platform.getCurrentSync().identity).createView({
   name: 'new-view',
   url: 'https://my-own-content.com',
});

getAllGroupIds

getAllGroupIds(): Promise<string[]>
Gets the IDs of all known groups

Returns Promise<string[]>
The group IDs of all groups

getAttached

getAttached(clientId): Promise<string[]>
Gets a list of windows that are attached to the given window
Parameters
- clientId: string
  The client id of the window to get the attached windows for
Returns Promise<string[]>
string[] - A promise resolving to a list of client ids of the attached windows
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
const attachedWindows = await server.getAttached('my-client-id');
```

getGroupIdForWindow

getGroupIdForWindow(identifier): Promise<string>
Gets the group ID for the given window.
Parameters
- identifier: string | number
  Either the native window ID (as a number), or the client ID of the window (as a string)
Returns Promise<string>
The group ID

Throws
An error if the ID provided is invalid.

getLayout

getLayout(): Promise<SnapLayout>
Retrieves the current layout

Returns Promise<SnapLayout>
The layout object

getWindowResizable

getWindowResizable(identifier): Promise<string>
Gets the resizable state for the given window.
Parameters
- identifier: string | number
  Either the native window ID (as a number), or the client ID of the window (as a string)
Returns Promise<string>
The resizable state

Throws
An error if the ID provided is invalid.

getWindowsInGroup

getWindowsInGroup(groupId): Promise<{
clientId: string;
nativeId: number;
}[]>
Gets an array of windows in a given group
Parameters
- groupId: string
  The group ID
Returns Promise<{
clientId: string;
nativeId: number;
}[]>
The windows in the group, or an empty array if the group does not exist.

hasAttachments

hasAttachments(clientId): Promise<boolean>

Checks if the given window has any attachments

Parameters

clientId: string
The client id of the window to check

Returns Promise<boolean>

Promise - True if the window has attachments, false otherwise

Example

const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
const hasAttachments = await server.hasAttachments('my-client-id');

launch

launch(options): Promise<LaunchResult>
Launches a new process and registers it with the Snap Server
Parameters
- options: LaunchOptions
  a set of options specifying the process to launch LaunchOptions
Returns Promise<LaunchResult>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();
await server.launch({
  path: 'C:\\Windows\\System32\\notepad.exe',
  client_id: 'my-notepad-client-id',
});
```

minimizeGroup

minimizeGroup(groupId): Promise<void>
Minimizes all windows in the given group
Parameters
- groupId: string
  The group ID
Returns Promise<void>

once

once<TEventName>(eventName, handler): void
Adds an event handler for the given event that will only be called once
Type Parameters
- TEventName extends
      | "all-events"
      | "client-registered"
      | "client-unregistered"
      | "move-size-completed"
      | "clients-attached"
      | "client-detached"
      | "groups-changed"
      | "client-activated"
      | "client-deactivated"
Parameters
- eventName: TEventName
  The name of the event to listen for
- handler: ((...eventArg: SnapServerEventTypes[TEventName]) => void)
  The handler to call when the event is fired
  - - (...eventArg): void
    - Parameters
      Rest...eventArg: SnapServerEventTypes[TEventName]
      Returns void
Returns void
void

See
SnapServerEventTypes

prepareToApplySnapshot

prepareToApplySnapshot(snapshotPayload?, customClientIdMapper?): Promise<void>

Prepares the Snap server to apply a new snapshot, potentially modifying the given payload

Parameters

OptionalsnapshotPayload: ApplySnapshotPayload
The payload for applySnapshot
OptionalcustomClientIdMapper: ((id: string) => string)
An optional mapper function for renaming any client IDs in the snapshot that are already in use in Snap. If not provided, then a default mapper function will be used when necessary, whose logic is as follows: For IDs containing three or more parts separated by a '/', the last part will be replaced with a new GUID. For other IDs, the the entire ID will be replaced with a new GUID. For example, <prefix>/<appId>/<instanceId> would be replaced with <prefix>/<appId>/<a new GUID>, and <another client ID> would be replaced with <a new GUID>. Client IDs referenced in the snapshot payload that are not already in use in Snap will be unchanged.
- - (id): string
  - Parameters
    - id: string
    Returns string

Returns Promise<void>

Promise

Example

This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout

  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
           async applySnapshot(payload: OpenFin.ApplySnapshotPayload, identity?: OpenFin.Identity): Promise<void> {
             await snapServer.prepareToApplySnapshot(payload);
             await super.applySnapshot(payload, identity);
             await snapServer.applySnapshot(payload.snapshot);
           }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});

registerWindow

registerWindow(clientId, windowHandle, resizingBehavior?): Promise<void>
Registers the given platform native window handle with the Snap Server
Parameters
- clientId: string
  The client id to register the window with
- windowHandle: string
  The native window handle to register
- OptionalresizingBehavior: ResizingBehavior
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the native id '0x0000000000001234'
await server.registerWindow('my-client-id', '0x0000000000001234');
```

removeEventListener

removeEventListener<TEventName>(eventName, handler): void
Removes an event handler for the given event
Type Parameters
- TEventName extends
      | "all-events"
      | "client-registered"
      | "client-unregistered"
      | "move-size-completed"
      | "clients-attached"
      | "client-detached"
      | "groups-changed"
      | "client-activated"
      | "client-deactivated"
Parameters
- eventName: TEventName
  The name of the event to remove the handler for
- handler: ((...eventArg: SnapServerEventTypes[TEventName]) => void)
  The handler to remove
  - - (...eventArg): void
    - Parameters
      Rest...eventArg: SnapServerEventTypes[TEventName]
      Returns void
Returns void
void

See
SnapServerEventTypes

restoreGroup

restoreGroup(groupId): Promise<void>
Restores and brings to front all windows in the given group
Parameters
- groupId: string
  The group ID
Returns Promise<void>

setLayout

setLayout(layout, reset?): Promise<void>
Restores the given layout
Parameters
- layout: SnapLayout
  The layout object to restore
- reset: boolean = true
  Whether existing snap connections should be reset
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

const myLayout = { ... }
await server.setLayout(myLayout);
```

setWindowResizable

setWindowResizable(identifier, resizable): Promise<void>
Sets the resizable state for the given window.
Parameters
- identifier: string | number
  Either the native window ID (as a number), or the client ID of the window (as a string)
- resizable: boolean
Returns Promise<void>

start

start(options?): Promise<void>
Starts a new instance of Snap Server and connects to it passing an optional set of parameters
Parameters
- Optionaloptions: ServerOptions
  Options for the started server ServerOptions
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.start();
```

stop

stop(): Promise<void>
Shuts down the connected Snap Server instance

Returns Promise<void>
Promise

Class SnapServer

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns SnapServer

Example

Properties

__extensions

Optionalclient

emitter

OptionalneedToResetLayout

server_id

Optionalsnap_identity

Methods

addEventListener

Type Parameters

Parameters

Parameters

Returns void

Returns void

See

applySnapshot

Parameters

Returns Promise<void>

Example

attachWindows

Parameters

Returns Promise<void>

Example

connect

Returns Promise<void>

Example

decorateSnapshot

Parameters

Returns Promise<SnapSnapshot>

Example

detachFromGroup

Parameters

Returns Promise<void>

Example

enableAutoWindowRegistration

Returns Promise<(() => Promise<void>)>

Example

getAllGroupIds

Returns Promise<string[]>

getAttached

Parameters

Returns Promise<string[]>

Example

getGroupIdForWindow

Parameters

Returns Promise<string>

Throws

getLayout

Returns Promise<SnapLayout>

getWindowResizable

Parameters

Returns Promise<string>

Throws

getWindowsInGroup

Parameters

Returns Promise<{ clientId: string; nativeId: number; }[]>

hasAttachments

Parameters

Returns Promise<boolean>

Example

launch

Parameters

Returns Promise<LaunchResult>

Example

minimizeGroup

Parameters

Returns Promise<void>

once

Type Parameters

Parameters

`Optional`client

`Optional`needToResetLayout

`Optional`snap_identity

Returns Promise<{
clientId: string;
nativeId: number;
}[]>