You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: hub/apps/develop/launch/launch-snipping-tool.md
+35-35Lines changed: 35 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,24 @@
1
1
---
2
2
title: Launch Snipping Tool
3
-
description: This topic describes how to use the new protocol launch framework for Snipping Tool. Your app can use these URI schemes to launch the Snipping Tool capture overlay to create a new snip or recording.
3
+
description: This topic describes how to use the new protocol launch framework for Snipping Tool. Your app can use these URI schemes to launch Snipping Tool's capture overlay to create a new snip or recording.
4
4
ms.date: 02/14/2025
5
5
ms.topic: concept-article
6
6
keywords: windows 11, uri, snipping tool, capture
7
7
ms.localizationpriority: medium
8
8
ms.custom: RS5
9
-
# customer-intent: As a Windows developer, I want to learn about the ms-screenclip URI scheme so that I can integrate it into my application to programmatically launch the Snipping Tool. This will allow my application to trigger a snip experience directly, enabling users to take screenshots seamlessly without manually opening the Snipping Tool.
9
+
# customer-intent: As a Windows developer, I want to learn about the ms-screenclip URI scheme so that I can integrate it into my application to programmatically launch Snipping Tool. This will allow my application to trigger a snip experience directly, enabling users to take screenshots seamlessly without manually opening Snipping Tool.
10
10
---
11
11
12
12
# Launch Snipping Tool
13
13
14
-
This article specifies the protocol for integrating first and third-party applications with the Windows Snipping Tool using the **ms-screenclip:** URI (Uniform Resource Identifier) scheme. The protocol facilitates the capture of images and video (with audio) via the Snipping Tool. App callers can customize and choose which Snipping Tool features their app will display. The protocol is designed to offer flexibility, security, and ease of use, aligning closely with familiar HTTP-based interactions. This shift can make the protocol more intuitive for developers and facilitate its integration with web technologies.
14
+
This article specifies the protocol for integrating first and third-party applications with the Windows Snipping Tool using the **ms-screenclip:** URI (Uniform Resource Identifier) scheme. The protocol facilitates the capture of images and video (with audio) via Snipping Tool. App callers can customize and choose which Snipping Tool features their app will display. The protocol is designed to offer flexibility, security, and ease of use, aligning closely with familiar HTTP-based interactions. This shift can make the protocol more intuitive for developers and facilitate its integration with web technologies.
15
15
16
16
> [!NOTE]
17
17
> This protocol launch replaces the previous existing experience documented [here](launch-screen-snipping.md).
18
18
19
19
## Supported features
20
20
21
-
The Snipping Tool protocol supports the following features:
21
+
sSnipping Tool protocol supports the following features:
22
22
23
23
- Rectangle Capture
24
24
- Freeform Capture
@@ -33,8 +33,8 @@ The Snipping Tool protocol supports the following features:
33
33
34
34
**ms-screenclip:** takes the following parameters:
35
35
36
-
-**Scheme:**`ms-screenclip` - The custom scheme for the Snipping Tool protocol.
37
-
-**Host:** Defines the Snipping Tool operation to perform (`capture` for snipping and recording, `discover` for querying capabilities)..
36
+
-**Scheme:**`ms-screenclip` - The custom scheme for Snipping Tool's protocol.
37
+
-**Host:** Defines the Snipping Tool operation to perform (`capture` for snipping and recording, `discover` for querying capabilities).
38
38
-**Path:** Specifies the media type to capture, such as an image (`/image`) or video (`/video`).
39
39
-**Query:** Parameters for the specified schema.
40
40
@@ -60,16 +60,16 @@ The Snipping Tool protocol supports the following features:
60
60
|`host`| string (enum) | yes | Specifies the **Snipping Tool action** to perform. Supported values: <br>- `capture` – Opens Snipping Tool to take a screenshot or recording. <br>- `discover` – Queries supported features. |`capture`|
61
61
|`path`| string (enum) | yes | Specifies the **type of media** being captured: <br>- `image` – Screenshot capture. <br>- `video` – Screen recording. | n/a |
62
62
|`enabledModes`| string (list) | no | Controls which snipping or recording modes are **enabled** in the UI. <br> - `RectangleSnip` <br> - `WindowSnip` <br> - `FreeformSnip` <br> - `RectangleRecord` <br> - `SnippingAllModes` (all image modes) <br> - `RecordAllModes` (all recording modes) <br> - `All` (all supported modes) | Defaults to the mode specified in the URI (`path`) |
63
-
|`auto-save`| boolean | no | Determines if the captured **Snip or Recording** should be **automatically saved** to the user's device. If `false`, the file is stored temporarily for retrieval via a token.|`false`|
63
+
|`auto-save`| boolean | no | Determines if the captured **Screenshot or Recording** should be **automatically saved** to the user's device. If `false`, the file is stored temporarily for retrieval via a token. |`false`|
64
64
|`redirect-uri`| URI | yes | Callback URI where the **Snipping Tool response** will be sent. Applications must register a handler for this protocol. | n/a |
65
65
66
66
### Discover Host
67
67
68
-
The Snipping Tool protocol supports a `discover` endpoint that allows applications to retrieve available features, supported modes, and protocol versions dynamically. This is useful for ensuring compatibility with future updates or querying what capture methods are available.
68
+
Snipping Tool protocol supports a `discover` endpoint that allows applications to retrieve available features, supported modes, and protocol versions dynamically. This is useful for ensuring compatibility with future updates or querying what capture methods are available.
69
69
70
70
### How to Use
71
71
72
-
To retrieve the Snipping Tool's supported capabilities, use the following URI:
72
+
To retrieve Snipping Tool's supported capabilities, use the following URI:
@@ -109,10 +109,10 @@ The response is a JSON object containing:
109
109
110
110
## EnabledModes
111
111
112
-
The enabledModes parameter is designed to give developers granular control over the available UI options when invoking the ms-screenclip protocol. This allows for a tailored user experience that matches the specific requirements of the calling application. By specifying the enabledModes parameter, developers can restrict the user's choices in the Snipping Tool UI to ensure the output format meets their expectations.
112
+
The **enabledModes** parameter is designed to give developers granular control over the available UI options when invoking the ms-screenclip protocol. This allows for a tailored user experience that matches the specific requirements of the calling application. By specifying the **enabledModes** parameter, developers can restrict the user's choices in Snipping Tool's UI to ensure the output format meets their expectations.
113
113
114
114
> [!NOTE]
115
-
> The FullScreenSnip mode is not supported in interactive mode at this time and should not be included in the enabledModes parameter.
115
+
> The FullScreenSnip mode is not supported in interactive mode at this time and should not be included in the **enabledModes** parameter.
116
116
117
117
### Supported modes
118
118
@@ -121,70 +121,70 @@ The **enabledModes** parameter can accept the following modes:
-**RecordAllModes:** Enables all recording modes (currently only RectangleRecord is available).
126
-
-**SnippingAllModes:** Enables all snipping (image capture) modes (RectangleSnip, WindowSnip, FreeformSnip).
127
127
-**All:** Enables all supported modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord).
128
128
129
129
> [!IMPORTANT]
130
-
> If the **enabledModes** parameter is is omitted, the Snipping Tool will default to the mode explicitly specified in the URI (e.g., `rectangle`, `freeform`).
130
+
> If the **enabledModes** parameter is omitted, Snipping Tool will default to the mode explicitly specified in the URI (e.g., `rectangle`, `freeform`).
131
131
>
132
-
> - If a mode is explicitly specified in the URI (such as rectangle), only that mode will be available in the Snipping Tool UI.
133
-
> - If no mode is specified and enabledModes is also not provided, the request is considered invalid and will be ignored.
132
+
> - If a mode is explicitly specified in the URI (such as rectangle), only that mode will be available in Snipping Tool's UI.
133
+
> - If no mode is specified and **enabledModes** is also not provided, the request is considered invalid and will be ignored.
_Explanation: This command launches the Snipping Toolwith only the rectangle snipping option enabled. The user will only be able to select a rectangular region for capture._
141
+
_Explanation: This command launches Snipping Tool's overlay with only the rectangle snipping mode enabled. The user will only be able to select a rectangular region for capture._
142
142
143
143
### Example 2: Enable Rectangle Snip and Window Snip
_Explanation: This command launches the Snipping Toolwith both the rectangle and window snipping modes enabled. The user can choose between capturing a rectangular area or an entire window._
147
+
_Explanation: This command launches Snipping Tool's overlay with both the rectangle and window snipping modes enabled. The user can choose between capturing a rectangular region or an entire window._
_Explanation: This command launches the Snipping Tool with all supported image snipping modes (RectangleSnip, WindowSnip, FreeformSnip). The FullScreenSnip mode is excluded from interactive mode and will not be enabled._
153
+
_Explanation: This command launches Snipping Tool's overlay with all supported image snipping modes (RectangleSnip, WindowSnip, FreeformSnip). The FullScreenSnip mode is excluded from interactive mode and will not be enabled._
_Explanation: This command launches the Snipping Toolwith only the recording mode enabled. The user can only choose the rectangle recording mode._
159
+
_Explanation: This command launches Snipping Tool's overlay with only the recording mode enabled. The user can only choose the rectangle region to record._
160
160
161
161
### Example 5: Enable Multiple Snipping and Recording Modes
_Explanation: This command launches the Snipping Toolwith both rectangle snip and rectangle recording modes available. Users can either snip a rectangle or record the selected area._
165
+
_Explanation: This command launches Snipping Tool's overlay with rectangle recording, rectangle and freeform snipping modes available. Since freeform mode was specified in the URI, it will be the default pre-selected mode. Users can choose to snip in freeform, rectangle, or record a the selected region.._
_Explanation: This request does not specify any mode, making it invalid. The Snipping Tool will ignore the call._
177
+
_Explanation: This request does not specify any mode, making it invalid. Snipping Tool will ignore the call._
178
178
179
179
## Key considerations
180
180
181
181
-**Mode Restrictions:** Developers should ensure that enabling specific modes aligns with the expected behavior of their application. Restricting UI options helps maintain a consistent user experience and ensures the resulting capture matches the application's needs.
182
182
-**Unsupported Modes:** The FullScreenSnip mode is not supported and should not be included in the `enabledModes` parameter.
183
-
-**Default Behavior:** If no enabledModes parameter is specified, all modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord) are available by default.
183
+
-**Default Behavior:** If no `enabledModes` parameter is specified, all modes (RectangleSnip, WindowSnip, FreeformSnip, RectangleRecord) are available by default.
184
184
185
185
## Security Considerations
186
186
187
-
Important: The Snipping Tool does not validate the redirect-uri parameter. It is the responsibility of the calling application to ensure that:
187
+
Important: Snipping Tool does not validate the redirect-uri parameter. It is the responsibility of the calling application to ensure that:
188
188
189
189
- The `redirect-uri` points to a trusted destination.
190
190
- The `redirect-uri` does not expose the captured content to unauthorized applications.
@@ -196,26 +196,26 @@ Response if expected parameters **aren't** supplied or overloaded.
196
196
197
197
## Responses to the caller
198
198
199
-
To ensure the response back to the caller via `redirect-uri` follows HTTP-based interaction principles, the response will mimic the structure of an HTTP response but will be conveyed through URI query parameters. This approach keeps the interaction web-standard compliant and familiar to developers.
199
+
To ensure the response back to the caller via `redirect-uri` follows HTTP-based interaction principles, the response will mimic the structure of an HTTP response, but will be conveyed through URI query parameters. This approach keeps the interaction web-standard compliant and familiar to developers.
200
200
201
201
### Use of shared tokens
202
202
203
203
The use of the `SharedStorageAccessManager` class and of sharing tokens is subject to the following requirements and restrictions:
204
204
205
-
- A sharing token can only be redeemed one time. After that, the token is no longer valid.
205
+
- A sharing token can only be redeemed once. After that, the token is no longer valid.
206
206
- A sharing token expires after 14 days and is no longer valid.
207
-
- The source app cannot provide more than one thousand sharing tokens. After a token is redeemed, removed, or expires, however, it no longer counts against the quota of the source app.
207
+
- The source app cannot provide more than 1000 sharing tokens. After a token is redeemed, removed, or expires, however, it no longer counts against the quota of the source app.
208
208
209
209
### Response parameters
210
210
211
211
The following parameters are returned in the redirect URI:
| Reason | String | The outcome and explanation for the snipping outcomes.|
216
-
| Token (for success) | String | A token representing the captured media, which the application can use to access the file. |
217
-
| code | Int | The HTTP status code equivalent to provide a more granular understanding of the outcome. |
218
-
| x-request-correlation-id | String | A unique identifier value attached to requests and messages that allow reference to a particular transaction or event chain. |
| Reason | String | The outcome and explanation for the snip. |
216
+
| Token (for success) | String | A token representing the captured media, which the application can use to access the file. |
217
+
| code | Int | The HTTP status code equivalent to provide a more granular understanding of the outcome. |
218
+
| x-request-correlation-id | String | A unique identifier value attached to requests and messages that allows reference to a particular transaction or event chain. |
219
219
220
220
## Retrieving a token
221
221
@@ -242,7 +242,7 @@ The following table lists the status codes that can be returned in the redirect
242
242
243
243
## Caller example
244
244
245
-
Below is a table displaying examples of full URIs constructed to initiate different types of snipping sessions using the screenclip: protocol. Each URI example demonstrates a combination of parameters to illustrate how you can customize the snipping tool's behavior for different use cases.
245
+
Below is a table displaying examples of full URIs constructed to initiate different types of snipping sessions using the screenclip: protocol. Each URI example demonstrates a combination of parameters to illustrate how you can customize Snipping Tool's behavior for different use cases.
0 commit comments