Name: import snapshot

Type: command

Syntax: import snapshot [from rect[angle] <rectDescription>] [of {<objectRef> | <stackRef>}] [{with | without} effects] [at size <sizeDescription>]

Syntax: import snapshot from {<objectRef> [{with | without} effects] | <stackRef>} [at size <sizeDescription>]

Summary:
Creates an <image> of a portion of the screen, a portion of a stack 
window, or a specific object and sets <it> to the long id of the 
created <image>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, mobile

Security: privacy

Example:
# rectangle coordinates are absolute (based on whole screen)
import snapshot from rectangle 100,100,500,400

Example:
# rectangle coordinates are absolute
import snapshot from rectangle (the rect of group "Picture")

Example:
# snapshot includes the object with blendLevel, ink, and graphic effects
import snapshot from button "myBtn" with effects

Example: 
# take snapshot of the stack window
import snapshot from stack the windowID of this stack

Example:
# rectangle coordinates are relative to the stack window
local myRect, winID
put the rect of control 2 into myRect
put the windowID of this stack into winID
import snapshot from rect myRect of window winID

Example:
# snapshot is resized to indicated width, height
import snapshot from the selectedObject at size 100,100

Parameters:
rectDescription:
Specifies the edges of the rectangular area to be imported, separated by
commas, in the same order as the <rectangle(property)> property (left, 
top, right, bottom). If a <stackRef> (the <windowID> of a stack) is specified, 
the <rectDescription> is given in relative (window) coordinates; otherwise, 
it is given in absolute coordinates.

stackRef:
Any valid stack window reference (using the <windowID> property of the stack).

objectRef:
Any valid card or control <object reference>.

sizeDescription:
The width and height of the snapshot in pixels, in the form *height,width*.

Description:
Use the <import snapshot> <command> to place a screenshot in the
<current stack>.

The <import snapshot> <command> creates a new <image> in the center of
the <current card> and places the snapshot in the <image> and sets 
the <it> variable to long id of the created <image>.

iOS supports both the object and screen snapshot variants of the 
<import snapshot> command. In the screen snapshot case, coordinates 
are given relative to the top-left of the screen, including the 
area where status bar is, but not including the status bar itself.

If you do not specify the rect[angle] <token> or an <objectRef>, LiveCode 
displays a crosshairs <cursor>. Click at one corner of the rectangular
area to be imported and drag to the opposite corner to <select> the area.

If taking a snapshot using the rect[angle] <token> and <rectangle(property)> 
of an object, the coordinates in the <rectDescription> are absolute (screen) 
coordinates. The portions of all windows and other objects on the screen 
that intersect the <rectDescription> will be included in the snapshot. 

If taking a snapshot using the rectangle <token>, <rectDescription>, and 
a <stackRef>, the coordinates in <rectDescription> are relative to the 
top left corner of the stack you specify. The portions of all 
objects that intersect the <rectDescription> will be included in the
snapshot. In addition, if the window is partly overlapped by another 
window, whatever is visible on the screen within that <rectDescription> 
is placed in the snapshot. In other words, you cannot take a snapshot 
of a part of a window that is hidden by another overlapping window.

If taking a snapshot using an <objectRef>, the object is rendered into 
an <image> as if no other objects existed around it. The snapshot is taken 
without applying the object's <blendlevel>, <ink>, or graphic effects. 
You can take a snapshot of an object regardless of its visibility or open 
status--in particular, snapshots can be taken of objects that are not on 
the current card or in stacks that are not open.

Use the `at size sizeDescription` extension if you wish the engine 
to resize the snapshot taken to the dimensions specified.

While you take the snapshot, LiveCode hides its own IDE windows (such 
as the Tools palette).

The format of the resulting <image> depends on the current setting of the
<paintCompression> <property>.

To import a snapshot for a portion of a stack you use the form:

    import snapshot from rect[angle] rectDescription of stack winID 

Where *winID* is the <windowID> property of the given stack.

To import a snapshot of a specific (non-stack) object, use the form:

    import snapshot from objectRef

Where <objectRef> is any control or card <object reference>, or any
<expression> evaluating to a control or card <object reference>.

To import a snapshot of an object, including its <blendLevel>, <ink>, or 
graphic effects, use the `with effects` form: 

    import snapshot from objectRef with effects 

Where <objectRef> is any control <object reference>, or any 
<expression> evaluating to a control <object reference>.

To import a snapshot of an object in iOS use the form:

    import snapshot from objectRef

To import a snapshot of the screen in iOS use the form:

    import snapshot from rectangle rectDescription

>*Note:*  There is no way to render the status bar without using private
> features of the iOS API. Therefore, if your snapshot rectangle
> includes part of the screen where the status bar is, it will be
> clipped out.

Changes: The `at size` variant, which allows resizing of the imported 
snapshot to specified dimensions, was added in version 6.0.

References: export snapshot (command), expression (glossary), 
import (command), current stack (glossary), current card (glossary),
command (glossary), object reference (glossary), property (glossary), 
image (glossary), cursor (property), blendlevel (property), ink (property), 
paintCompression (property), rectangle (property), select (glossary), 
token (glossary), windowID (property), it (keyword)

Tags: multimedia

