Livecode Wiki

Specifies the file associated with a player or image.Syntax:

set the filename of {<image> | <player>} to {<filePath> | <URL>}


set the filename of image "Animation" to "/HD/Projects/blipvert.gif"
set the filename of last player to ""

Use the filename property to reference a separate file that holds the data for an image or player that's a referenced control.

The contents of an image can reside either in the stack or in a separate file. If an image's filename is empty, the image uses its own data, which resides in the stack, instead of loading a separate file. (You can import an image with the import command, or paint an image with the paint tools. ) Setting an image's filename property to the name and location of a file deletes the previous contents of the image.

Using an image from a separate file reduces memory use, since the image does not need to be loaded into memory unless it is in use. But it increases the time it takes to go to a card containing the image, since the file must be loaded from the disk it's on or from the Internet.

The contents of a player must reside in a separate file that is specified in the player's filename property. If a player's filename is empty, the player does not display any data. The file specified by the filePath or URL must be in a format supported by AVFoundation on Mac and DirectShow on Windows.

   set the filename of player "My Player" to "SecondMovie. mov"
   set the currentTime of player "My Player" to zero

If you specify a URL for a streaming a movie file, LiveCode displays the movie sequentially as it downloads. Otherwise, LiveCode must download the entire file before you can play it. To pre-fetch a file from the Internet in order to speed up access to it, use the load command before visiting the card that holds the player or image that references the file's URL.

You can use the "New Referenced Control" submenu in the File menu to create a new image or player which references the contents of a file you specify. You can also set the filename to an absolute path or relative path by changing the Source field in the image's or player's property inspector.

To take full advantage of Hi-DPI, images must be provided at appropriate sizes for different densities. This can be done by having multiple image files in the same location named appropriately (with the image object referencing the image file at the natural density). The naming convention is as follows:

- @ultra-low. - @ultra-low. - 0.25x - @extra-low. - 0.5x - @low. - 0.75x - @medium. / . - 1x - @high. - 1.5x - @extra-high. / @2x - 2x - @ultra-high. - 4x

When an image is required, the current scale factor is rounded up to the nearest standard density (one of 0.25, 0.5, 0.75, 1, 1.5, 2 and 4). The image with the lowest scale factor that is greater or equal to the nearest standard density is then selected. For example, if the scale factor is 1.75 and there is an extra-high image available, then that is used. Images should be created at appropriately scaled pixel size. If the natural size of an image is x points wide and y points high, the scaled versions should be x scale pixels wide and y scale pixels high in order to have the same natural size. You should take care that the natural size of the image scales to integer pixel sizes, as the logical point size of the image is rounded up to the nearest integer. If this is not practical for a given image, you may need to design your apps to handle slightly different resulting image sizes.

Changes: The use of QuickTime was deprecated in version 8.1 of LiveCode with new defaults for dontUseQT and dontUseQTEffects as true on all systems apart from pre OS X 10.8. The Windows build of LiveCode no longer supports any QuickTime features and setting the dontUseQT and dontUseQTEffects will have no effect. Additionally QuickTime does not include 64 bit support and therefore can not be supported on OS X 64 bit builds of LiveCode.

Support for Density Mapped Images was introduced in version 6. In previous versions, the filename of an image would only be able to use that particular image for display. Images with differing resolution are now supported, allowing applications to take full advantage of Hi-DPI.

The URL option was introduced in version 1.1. In previous versions, the filename of an image or player always specified a file path on the local system, and files on the Internet could not be used.

See also: shortFilePath (function),saveStackRequest (message),fileType (property),constantMask (property),