<doc>
	<legacy_id>1176</legacy_id>
	<name>export snapshot</name>
	<type>command</type>

	<syntax>
		<example>export snapshot [from rect[angle] <i>rectangle</i>] [of <i>object</i>] [(with | without) effects] ... | [from <i>object</i>] [{with|and} metadata <i>metadata</i>] to {file <i>filePath </i>| <i>container</i>} [as <i>format</i>] [with mask <i>maskFile</i>]</example>
		<example>export snapshot [from rect[angle] rectangle] of <i>object</i> [(with | without) effects] ... | [from <i>object</i>] [at size width, height] [{with|and} metadata <i>metadata</i>] to {file <i>filePath</i> | container} [as <i>format</i>] [with mask <i>maskFile</i>]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Creates a picture file from a portion of the screen.</summary>

	<examples>
<example>export snapshot with effects to file "Test.ppm"</example>
<example>export snapshot from rect "0,0,200,200" to file "Nav.jpg" as JPEG</example>
<example><p>export snapshot from Field 1 to file "File1.png" as PNG</p></example>
<example>export snapshot to pictVariable as GIF</example>
<example>export snapshot from rect "0,0,200,200" to pictVariable as PNG</example>
<example>export snapshot from Group 1 with metadata theMetadataArray to file "File2.jpg" as JPEG</example>
	</examples>

	<history>
		<introduced version="2.1">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="6.0">At size extension added</changed>
<changed version="4.6">iOS support added</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
	</platforms>

	<classes>
	</classes>

	<security>
	</security>


	<classification>
		<category>Images  Multimedia</category>
		<category>Files, Folders,  Resources</category>
	</classification>

	<references>
		<function tag="screenRect">screenRect Function</function>
		<command tag="export">export Command</command>
		<command tag="import snapshot">import snapshot Command</command>
		<property tag="rectangle">rectangle Property</property>
		<property tag="windowID">windowID Property</property>
	</references>

	<description>
	<overview>Use the <b>export snapshot</b> <glossary tag="command">command</glossary> to export a screenshot to a <keyword tag="file">file</keyword> or <glossary tag="container">container</glossary>.</overview>

		<parameters>
  <parameter>
    <name>rectangle</name>
    <description>Specifies the edges of the rectangle to be imported, separated by commas, in the same order as the rectangle property (left, top, right, bottom). If a window, stack or object is specified, the rectangle is given in relative (window) coordinates; otherwise, it is given in absolute coordinates.</description>
  </parameter>
  <parameter>
    <name>filePath</name>
    <description>Specifies the name and location of the file you want to export to. If you specify a name but not a location, the file is created in the <property tag="defaultFolder">defaultFolder</property>.</description>
  </parameter>
  <parameter>
    <name>container</name>
    <description>A reference to a container, usually an image or a URL.</description>
  </parameter>
  <parameter>
    <name>format</name>
    <description>One of the following: paint, JPEG, GIF, or PNG.</description>
    <options title="">
      <option>
        <item>paint</item>
        <description>save the exported image in PBM format (paint) format</description>
      </option>
      <option>
        <item>JPEG</item>
        <description>save the exported image in JPEG format</description>
      </option>
      <option>
        <item>GIF</item>
        <description>save the exported image in GIF format</description>
      </option>
      <option>
        <item>PNG</item>
        <description>save the exported image in PNG format</description>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>maskFile</name>
    <description>Specifies the name and location of a file to export as an image mask. You can use a maskFile only when exporting in PBM format (paint).</description>
  </parameter>
  <parameter>
    <name>effect</name>
    <description>Specifies whether graphic effects and a blendLevel should be applied to the object before rendering export.</description>
  </parameter>
  <parameter>
    <name>metadata</name>
    <description>The <i>metadata</i> is an array of metadata. Currently the only key supported is "density" with a value in pixels per inch (ppi).</description>
  </parameter>
  
  <parameter>
    <name>...</name>
    <description>Denotes the usual possible suffixes for the export snapshot command.</description>
  </parameter>		</parameters>

	<value></value>
	<comments>If you use the form export <i>format</i> to..., the selected <keyword tag="image">image</keyword> is exported.<p>The <b>export snapshot</b> ... as paint form exports the image as a PBM, PGM, or PPM file, depending on the screen depth. (Optionally, you can specify a location for the mask file.) The <b>export snapshot</b> ... as JPEG form exports as a JPEG file, and the <b>export snapshot</b> ... as PNG form exports as a PNG file. If you do not specify a <i>format</i>, the file is exported as <glossary tag="PBM">PBM</glossary>, PGM, or <glossary tag="PPM">PPM</glossary>.</p><p></p><p>iOS supports both the object and screen snapshot variants of the export snapshot command. In the screen snapshot case, coordinates are given relative to the top-left of the screen and include the status bar.</p><p></p><p></p><p></p><tip> If the <keyword tag="image">image</keyword> has an <glossary tag="alpha channel">alpha channel</glossary>, the <b>export snapshot</b><i> ... as</i> PNG form creates a 32-bit PNG file.</tip><p>If taking a snapshot of an object, the rectangle's coordinates are relative to the top left corner of the card containing the object. 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 or ink. 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.</p><p></p><p>If you don't specify a <i>rectangle</i>, LiveCode displays a crosshairs <property tag="cursor">cursor</property>. Click at one corner of the rectangle to be imported and drag to the opposite corner to <command tag="select">select</command> the area.</p><p></p><p>If you specify a <property tag="windowID">windowID</property>, the <i>rectangle's</i> coordinates are relative to the top left corner of the window you specify. However, if the window is partly overlapped by another window, whatever is visible on the screen within that rectangle 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.</p><p></p><p>Use the <b>at size</b> extensions if you wish the engine to resize the snapshot taken to the dimensions specified.</p><p></p><p>To export a snapshot for a portion of a stack you use the form:</p><p><b>export snapshot</b> from rect[angle] of window <property tag="windowID">windowID</property> to ...</p><p>Where <i>windowId</i> is the windowId property of the required stack.</p><p></p><p>To export a snapshot of a specific (non-stack) object, use the form:</p><p><b>export snapshot</b> from [rect[angle]] of 'chunk' to ...</p><p>Where 'chunk' is any chunk expression resolving to a control, or any expression evaluating to a control reference.</p><p></p><p>To export a snapshot of an object in iOS use the form:</p><p><b>export snapshot</b> from [rectangle <i>rect</i> of] <i>object</i></p><p></p><p>To export a snapshot of the screen in iOS use the form:</p><p><b>export snapshot</b> from rectangle <i>rect</i></p><p></p><p></p><p></p><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.</note><p></p><p></p><important> The 'at size' variant of the <b>export snaptshot</b> command is currently only when creating snapshots of objects.</important><p>&#9;</p></comments>
	</description>
</doc>