# Appendix A: Functions

The following is a list of all available functions and a complete description of each. For general information on how the External functions work and how you can use them in your calculations, please see the How to use Plug-ins PDF Document available on the CNS Plug-ins website.

## CNSImage_Convert

Title
  CNSImage_Convert
Format
  CNSImage_Convert( Image ; Type {; Width {; Height {; Resolution {; Depth {; Quality {; TargetSize }}}}}} )
Data Type Returned
  Image
Description
  The CNSImage_Convert function allows you to convert an image. You can change the type of the image as well as the width, height, resolution, and depth. If your target image type is JPEG or TIFF, you can set the Quality. If your target image type is JPEG, you can set the targetsize.
  For a list of image types, see "Reference: Image Types".
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Convert.
  - Type - The Type of the new Image. (Specify "" to keep the current Image Type. Types include: JPEG, GIF, PNG, BMP, EPS, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, and PDF.)
Parameters (Optional)
  - Width - The Width in pixels of the new Image. (Specify "" to keep the current Width.)
  - Height - The Height in pixels of the new Image. (Specify "" to keep the current Height.)
  - Resolution - The Resolution in pixels per inch of the new Image. (Specify "" to keep the current Resolution.)
  - Depth - The Bit-Depth of the new Image. (All settings may not work for all Image Types; Specify "" to keep the current Bit-Depth. Depths include: 1, 2, 4, 8, 16, 24, 32, -, 33, 34, 36, and 40.)
  - Quality - The Quality of the new Image. (Only available for JPEGs and TIFFs; Specify "" to keep the current Quality. You can also specify a number or keyword: min = 0, low = 256, normal = 512, high = 768, max = 1023, lossless = 1024.)
  - TargetSize - The Target File Size of the new Image. (Only available for JPEGs.)
Example
  CNSImage_Convert( MyImage ; "JPEG" ; 100 ; 100 ; 72 ; 32 ; 1024 )
  -> Returns a JPEG image 100 pixels wide with a resolution of 72, a depth of 32, and quality of 1024.
  CNSImage_Convert( MyImage ; "PNGf" ; 100 ; 100 ; 72 )
  -> Returns a PNG image 100 pixels wide with a resolution of 72.
Related
  Reference: Image Types

## CNSImage_Copy

Title
  CNSImage_Copy
Format
  CNSImage_Copy( Image )
Data Type Returned
  Image
Description
  This function is used in conjunction with the CNSImage_Import function to make a copy of the original image in case you need to populate the container field if the user cancels. Its use is limited to working around a bug in 7.0v3 and before when copying a container into itself.
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Copy
Example
  CNSImage_Copy( Importing::original )
  -> Returns a copy of the image in the "Importing::original" container field

## CNSImage_Crop

Title
  CNSImage_Crop
Format
  CNSImage_Crop( Image ; Top ; Left ; Bottom ; Right )
Data Type Returned
  Image
Description
  The CNSImage_Crop function allows you to create a new image based on part of an image. In other words, it takes an image, crops it to your specifications and then returns it to you.
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Crop.
  - Top ; Left - The pixel coordinates of the Top, Left corner of the Crop rectangle.
  - Bottom ; Right - The pixel coordinates of the Bottom, Right corner of the Crop rectangle.
Example
  CNSImage_Crop( MyImage ; 0 ; 0 ; 100 ; 100 )
  -> Returns a 100 square pixel area from the image in the "MyImage" container.

## CNSImage_Export

Title
  CNSImage_Export
Format
  CNSImage_Export( Image {; Path {; Prompt {; AllowConvert {; TypeList }}}} )
Data Type Returned
  String
Description
  This function allows you to save an image to any folder with any name. You can also export an image using a dialog. The function will return a string indicating the success or failure of the operation.
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Export.
Parameters (Optional)
  - Path - The Path and File Name the Image will be Exported to. (Specify "" or omit File Name to display Save File Dialog).
  - Prompt - A message to be displayed in the Save File Dialog.
  - AllowConvert - If True, this allows you to select an alternate File Type to Convert to as you Export. (Only available if the Save File Dialog is displayed.)
  - TypeList - A comma or semicolon-delimited list of Image File Types the user is Allowed to Convert to. (Valid Types are: JPEG, GIF, PNG, BMP, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, PDF)
Example
  CNSImage_Export( Image )
  -> Displays a save file dialog. You can edit the name of the file and navigate in the file dialog prior to saving.
  CNSImage_Export( Image ; "/Drive/folder/filename.jpg" )
  -> Saves an image to the folder "/Drive/folder/" with the name "filename.jpg".
  CNSImage_Export( Image ; "Drive/folder/" )
  -> Displays a save file dialog starting in the folder "Drive/folder/". You can edit the name of the file in the file dialog prior to saving.
  CNSImage_Export( Image ; "" ; "Please locate where you would like to save this image." )
  -> Displays a save file dialog with the prompt: "Please locate where you would like to save this image." . You can edit the name of the file in the file dialog prior to saving.
  CNSImage_Export( Image ; "Drive/folder/" ; "" ; True )
  -> Displays a save file dialog starting in the folder "Drive/folder/". You can edit the name of the file in the file dialog prior to saving and specify a different image format for the file to convert the image if you want.

## CNSImage_File_GetPathToDB

Title
  CNSImage_File_GetPathToDB
Format
  CNSImage_File_GetPathToDB
Data Type Returned
  String
Description
  This function will return the Hard Drive Path to the Folder containting the Front-most Database in FileMaker. This is similar to FileMaker's own Get(FilePath) function, but returns the Path in a nicer format, plus it doesn't include the Database File Name. If the front-most database is a hosted database, this function will return an error.
Example
  CNSImage_File_GetPathToDB
  -> Returns a path to the folder containing the front-most database in FileMaker.

## CNSImage_File_GetPathToFM

Title
  CNSImage_File_GetPathToFM
Format
  CNSImage_File_GetPathToFM
Data Type Returned
  String
Description
  This function will return the Hard Drive Path to the Folder containing the currently running FileMaker Application, be it FileMaker Pro, FileMaker Server, Web Publishing Engine, or a FileMaker Runtime.
Example
  CNSImage_File_GetPathToFM
  -> Returns the path to the folder containting the running FileMaker application.

## CNSImage_File_SelectFileWithDialog

Title
  CNSImage_File_SelectFileWithDialog
Format
  CNSImage_File_SelectFileWithDialog{( StartPath {; TypeList {; Prompt }} )}
Data Type Returned
  String
Description
  The CNSImage_File_SelectFileWithDialog function allows you to use a dialog to locate a file on your hard drive and returns the path of the chosen file. You can specify the starting folder by specifying the optional "StartPath" param. You can limit the type of files to choose from by using the optional "TypeList" param. You can also display a message in the dialog by using the optional "Prompt" param.
Parameters (Optional)
  - StartPath - The Path to the Folder to display when the dialog first opens.
  - TypeList - A comma or semicolon-delimited list of Image File Types the user is allowed to Choose. For a complete list of types, view the "Reference: Image Types" section of the Function Reference.
  - Prompt - An optional Prompt or Message to display on the dialog.
Example
  CNSImage_File_SelectFileWithDialog
  -> A dialog is shown to choose a file.
  CNSImage_File_SelectFileWithDialog( "~/Desktop/" )
  -> A dialog is shown with the current user's Desktop as the starting folder.
  CNSImage_File_SelectFileWithDialog( "" ; "JPG, PNG" )
  -> A dialog is shown to choose a file limited to JPG and PNG image types.
  CNSImage_File_SelectFileWithDialog( "" ; "JPG" ; "Please choose a JPG image:" )
  -> A dialog is shown to choose a file limited to JPG images with the prompt: "Please choose a JPG image:".
  CNSImage_File_SelectFileWithDialog( "" ; "" ; "Choose any image...." )
  -> A dialog is shown to choose any type of image with the prompt: "Choose any image...".
Related
  CNSImage_File_SelectFolderWithDialog

## CNSImage_File_SelectFolderWithDialog

Title
  CNSImage_File_SelectFolderWithDialog
Format
  CNSImage_File_SelectFolderWithDialog{( StartPath {; Prompt } )}
Data Type Returned
  String
Description
  You can use this function to choose a folder using a dialog box. You can use the optional "StartPath" param to specify which folder to display when the dialog first opens. You can use the optional "Prompt" param to display a message in the dialog box.
Parameters (Optional)
  - StartPath - The Path to the Folder to display when the dialog first opens.
  - Prompt - An optional Prompt or Message to display on the Dialog.
Example
  CNSImage_File_SelectFolderWithDialog
  -> Displays a dialog so you can choose folder. The chosen path is returned.
  CNSImage_File_SelectFolderWithDialog( "/" )
  -> Displays a dialog so you can choose a folder, starting with the startup volume or first drive.
  CNSImage_File_SelectFolderWithDialog( "Please choose a folder:" )
  -> Displays a dialog so you can choose folder with the prompt: "Please choose a folder". The chosen path is returned.
Related
  CNSImage_File_SelectFileWithDialog

## CNSImage_Filter

Title
  CNSImage_Filter
Format
  CNSImage_Filter( Image )
Data Type Returned
  Image
Description
  With this function, you can apply a QuickTime filter to an image. QuickTime comes with several built-in filters such as Brightness, ColorSync, HSL Balance, RGB Balance, Blur, Edge Detection, Emboss, Sharpen, Color Style, Color Tint, and more. There are also third party filters available on the net.
Parameters (Required)
  - Image - The Container that contains the Image you want to Filter.
Example
  CNSImage_Filter( MyImage )
  -> Opens the filter dialog, and returns the filtered image after you have made your selection.

## CNSImage_GetFromURL

Title
  CNSImage_GetFromURL
Format
  CNSImage_GetFromURL( URL )
Data Type Returned
  Image
Description
  You can download an image on the internet with this function. You can download fun images such as webcams, daily cartoons, or photos of the sun. You can also post new graphics for your solution to be downloaded across the net. Imagine if your database could check for new interface files on the net as part of your startup routine. Stop imagining, this is reality!
Parameters (Required)
  - URL - The full URL of the Image to Get.
Example
  CNSImage_GetFromURL( "http://www.cnsplug-ins.com/graphics/CNS_mini_logo.jpg" )
  -> Returns the "CNS_mini_logo.jpg" JPEG at the address "http://www.cnsplug-ins.com/graphics/CNS_mini_logo.jpg"

## CNSImage_GetInfo

Title
  CNSImage_GetInfo
Format
  CNSImage_GetInfo( Image {; Field } )
Data Type Returned
  String
Description
  The CNSImage_GetInfo function returns information about an image such as the format, width, height, resolution, depth, quality, and size. You can also using the "Item" parameter to retrieve a specific value such as the width of an image.
Parameters (Required)
  - Image - The Container that contains the Image you need the Info of.
Parameters (Optional)
  - Field - A specific Info Item you need. (If this parameter is not defined, all Info Items will be returned. You can specify multiple fields separated by a semicolon. Fields: type, width, height, hres, vres, depth, quality, filesize, displaywidth, displayheight, layers, pathname, filename, and storage. )
Example
  CNSImage_GetInfo( MyImage )
  -> Returns a return delimited string of information for the image in the "MyImage" container.
  CNSImage_GetInfo( MyImage ; "width" )
  -> Returns the width of the image in the "MyImage" container.
  CNSImage_GetInfo( MyImage ; "height;width" )
  -> Returns the height and width separated by a return.

## CNSImage_Import

Title
  CNSImage_Import
Format
  CNSImage_Import{( Path {; TypeList {; Prompt }} )}
Data Type Returned
  Image
Description
  The CNSImage_Import function allows you to easily import images into FileMaker. You can import by specifying a path to an image as well as using a dialog box to navigate to a desired image.
Parameters (Optional)
  - Path - The Path and File Name of the Image to Import. (Specify "" or omit File Name to display Open File Dialog).
  - TypeList - A comma or semicolon-delimited list of Image File Types the user is allowed to Import. Types include: JPEG, GIF, PNG, BMP, EPS, PICT, TIFF, PSD, FPIX, QTIF, SGI, TPIC, MACPAINT, and PDF.
  - Prompt - A message to be displayed in the Open File Dialog.
Example
  CNSImage_Import
  -> A dialog is shown to choose an image.
  CNSImage_Import( "/drive/folder/")
  -> A dialog is shown to choose a file starting at the folder "/drive/folder/"
  CNSImage_Import( "" ; "JPG, PNG" )
  -> A dialog is shown to choose a file limited to JPG and PNG image types.
  CNSImage_Import( "" ; "JPG" ; "Please choose a JPG image:" )
  -> A dialog is shown to choose a file limited to JPG images with the prompt: "Please choose a JPG image:".
  CNSImage_Import( "" ; "" ; "Choose any image...." )
  -> A dialog is shown to choose any type of image with the prompt: "Choose any image...".

## CNSImage_Reflect

Title
  CNSImage_Reflect
Format
  CNSImage_Reflect( Image; Direction )
Data Type Returned
  Image
Parameters (Required)
  - Image - The Container that contains the Image you want to Reflect.
  - Direction - The Direction to Reflect the Image. (Specify X or H for Horizontal, Y or V for Vertical, or B or L for Both Horizontal and Vertical.)
Example
  CNSImage_Reflect( Image; "H" )
  -> Reflects the image in the "Image" container field horizontally.

## CNSImage_Register

Title
  CNSImage_Register
Format
  CNSImage_Register( FirstName ; LastName ; RegNumber {; Option } )
Data Type Returned
  String
Description
  You can use this function to register a plug-in without having to use a dialog box. If you use the "Option" parameter, you can register via a dialog box using the "Dialog" value. You can also use value "Check" to test to see if the plug-in is registered or not. Finally, you can use the value "I Accept the License Agreement" to automatically accept the License Agreement dialog.
Parameters (Required)
  - First_Name - The Registration First Name you specified when you ordered. (See your Receipt.)
  - Last_Name - The Registration Last Name you specified when you ordered. (See your Receipt.)
  - Reg_Number - The Registration Number from your Receipt.
Parameters (Optional)
  - Option - Specify "Dialog" to enter your Registration Information in a Pop Up Dialog. (You can also specify "Dialog" as the FirstName parameter.) Specify "Check" to see if the plug-in is already Registered. (You can also specify "Check" as the FirstName parameter.) Specify "I Accept the License Agreement" to automatically accept the License Agreement dialog.

## CNSImage_Rotate

Title
  CNSImage_Rotate
Format
  CNSImage_Rotate( Image ; Degrees )
Data Type Returned
  Image
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Rotate.
  - Degrees - The Amount in Degrees that you want to Rotate the Image.
Example
  CNSImage_Rotate( Image ; 45 )
  -> Rotates the image in the "Image" field 45 degrees.

## CNSImage_Transform

Title
  CNSImage_Transform
Format
  CNSImage_Transform( Image ; X1 ; Y1 ; X2 ; Y2 ; X3 ; Y3 ; X4 ; Y4 )
Data Type Returned
  Image
Parameters (Required)
  - Image - A Container field that contains an Image or a Path and File Name to an Image you want to Transform.
  - X1 ; Y1 - The pixel coordinates of the Top, Left corner of the Transformation Rectangle.
  - X2 ; Y2 - The pixel coordinates of the Top, Right corner of the Transformation Rectangle.
  - X3 ; Y3 - The pixel coordinates of the Bottom, Right corner of the Transformation Rectangle.
  - X4 ; Y4 - The pixel coordinates of the Bottom, Left corner of the Transformation Rectangle.
Example
  CNSImage_Transform( Image ; 0 ; 0 ; 200 ; 0 ; 200 ; 500 ; 0 ; 500 )
  -> Transforms the image in the "Image" field. (Depending on the image, this would likely squish the image horizontally. For an example of this function in action, view the "Transform" example.)

## CNSImage_Version

Title
  CNSImage_Version
Format
  CNSImage_Version{( Option )}
Data Type Returned
  String
Parameters (Optional)
  - Option - You can use the following options: Specify "Auto Update" to return a more Auto Update friendly Version number, Specify "Configure" to bring up the "CNS Image" Configuration Dialog, Specify "About" to bring up the "CNS Image" Configuration Dialog with the About Tab as the first tab shown.
Example
  CNSImage_Version
  -> Returns the version number.
  CNSImage_Version( "About" )
  -> Brings up the "CNS Image" Configuration Dialog with the About Tab as the first tab shown.
  CNSImage_Version( "Configure" )
  -> Brings up the "CNS Image" Configuration Dialog
  CNSImage_Version( "Auto Update" )
  -> Specify "Auto Update" to return a more Auto Update friendly Version number

## Reference: Image Types

Title
  Reference: Image Types
Description
  CNS Image uses the QuickTime libraries to import, export, and convert your images. QuickTime does not support all image formats for all operations. Below is a break down of what can be imported, exported, and converted.
  Image Formats that can be Imported, or Converted From, on Both Mac OS X and Windows:

  Image Name | File Type | File Extensions
  --- | --- | ---
  JPEG | JPEG | .jpg; .jpeg; .jfif; .jpe
  GIF | GIFf | .gif
  PNG | PNGf | .png
  Windows Bitmap | BMPf | .bmp
  Macintosh PICT | PICT | .pct; .pict; .pic
  TIFF | TIFF | .tif; .tiff
  Photoshop | 8BPS | .psd
  QuickTime Image | qtif | .qif; .qti; .qtif; .qt
  Silicon Graphics | .SGI | .sgi
  Targa | TPIC | .tga; .tpic
  MacPaint | PNTG | .mac

  Image Formats that can be Imported, or Converted From, only on Mac OS X:

  Image Name | File Type | File Extensions
  --- | --- | ---
  PDF | PDF | .pdf

  Image Formats that can be Exported, or Converted To, on Both Mac OS X and Windows:

  Image Name | File Type | File Extensions
  --- | --- | ---
  JPEG | JPEG | .jpg; .jpeg; .jfif; .jpe
  PNG | PNGf | .png
  Windows Bitmap | BMPf | .bmp
  TIFF | TIFF | .tif; .tiff
  Photoshop | 8BPS | .psd
  QuickTime Image | qtif | .qif; .qti; .qtif; .qt
  Silicon Graphics | .SGI | .sgi
  Targa | TPIC | .tga
  MacPaint | PNTG | .mac

  Notes:
  - You can use either the Image Name or the File Type when specifying types in CNS Image.
  - On Mac OS X, CNS Image uses both the File Type and the File Extensions in the Import Dialog to determine if a file is a valid image type. On Windows, CNS Image only uses the File Extensions in the Import Dialog. When exporting images from your database, CNS Image will append the first listed file extension to the file name.
  - When using the CNSImage_Convert function, GIF images will be auto-converted to PNG images unless you specify another supported image type. PDF images will be auto-converted to JPEG images. When using the CNSImage_GetFromURL function, GIF images will automatically be converted to PNG images.
  - QuickTime does not have support for Importing or Exporting EPS images, so CNS Image will be unable to work with any "by reference" EPS images. This also means that CNSImage_Import will not be able to import EPS images. However, if FileMaker is used to Import (and store) an EPS image, CNS Image can manipulate the "JPEG Preview" stored in the container.
  - On Windows, if you paste an image into a container, the underlying format is a Windows MetaFile, DIB, or OLE format, which is incompatible with QuickTime. CNS Image will be able to manipulate the "JPEG Preview" though.

## Reference: Paths

Title
  Reference: Paths
Description
  You can use the following path types in order to reference images in CNS Image functions:
  imagemac:/HDName/folder/file.ext
  imagewin:/C:/folder/file.ext
  image:/POSIXpath/
  /Volumes/VolumeName/Folder/file.ext
  c:\folder\file.ext
  VolumeName:Folder:file.ext
  /C/Folder/file.ext
  ~/Desktop/file.ext