DropTools: stsImageWell

stsImageWell

Version 1.1.2

Sons of Thunder Software, Inc.

Free

Description

The

stsImageWell

DropTool is a LiveCode-based version of the Mac OS X "imageWell" control. It allows the user to insert an image into the control for whatever purposes your application may require.

Kind of DropTool

Behavior-based

Interface Support

Unless specifically stated, this control will function properly on all platforms, although its look-and-feel is intended for the platforms listed in the table to the left.

Custom	Mac OS X	Windows	Linux	iOS	Android

Extra Features

	"About" Stack
	"Inspector" Stack

Screenshots

Normal

With Focus

Scaled to Fit

Cropped and Centered

Usage Notes

You can add an image in one of the following ways:

The user can drag an image file from the desktop and drop it onto the stsImageWell control.

The user can select a chunk of image data from a graphics program, then click on the stsImageWell control to give it focus, and then paste the image data from the clipboard.

The user can select an image file on the desktop, copy it to the clipboard, then click on the stsImageWell control to give it focus, and then paste the image file in the clipboard.

You can programmatically point to a LiveCode image object and the stsImageWell control will display the image.

The stsImageWell control can be set to automatically scale an image to fit its size or visually center and crop the image if it's larger than the stsImageWell control (the default is to center and crop). You can also restrict what kinds of image files can be dropped onto it.

The following tables show you how to interact with the DropTool from your scripts:

Custom Properties

Property	Possible Values	Notes
uSTSImageWell_Filter	"all" or a comma-delimited list of image extensions (with or without spaces between the items)	This indicates what image types the user is allowed to drop on the control.
uSTSImageWell_ImagePath	A file path	This holds the file path to the image currently displayed in the control (if applicable). This property is technically read/write, although you should treat it as read-only so you can find out where the image is located on disk. You can set this property to cause an image a the provided path to be displayed in the control, but it is not recommended as there is no validation on the path at all (it is a "raw" assignment). For assigning an image path, you should set the uSTSImageWell_FilePath property instead. Note that this property will be empty if an image was put into the control by another method (setting an object ID or pasting in raw image data).
uSTSImageWell_ImageData	Raw imageData	This holds the raw image data for the image currently displayed in the control (if applicable). Note that this property will be empty if an image was put into the control by another method (setting an object ID or assigning a path/dropping a file).
uSTSImageWell_ImageID	Object reference to an image	This holds the ID of a LiveCode image object that is being displayed in the control (if applicable). Note that this property will be empty if an image was put into the control by another method (pasting in raw image data or assigning a path/dropping a file).
uSTSImageWell_ShowFocusBorder	This holds a true/false value and is used to show/hide the focus border on the control, and is used internally for this purpose (although you can manipulate it yourself if you like).
uSTSImageWell_FilePath	A file path	This is used to assign a dropped file to the control, so long as it is valid. It must be a valid path, use an image extension, and be one of the file types supported by the uSTSImageWell_Filter.
uSTSImageWell_ScaleToFit	"true" or "false"	This determines whether the image in the control is scaled to fit the bounds of the control or not. In all cases, images are resized proportionately, and with the "best" resize quality.

Messages Handled

Message	Actions Taken	Passed?
backspaceKey	This dispatches an "stsImageWell_Delete" message to the control before deleting any image that might be in the control.	No
deleteKey	This dispatches an "stsImageWell_Delete" message to the control before deleting any image that might be in the control.	No
focusIn	Shows the focus border.	Yes
focusOut	Hides the focus border.	Yes
commandKeyDown	Allows for the setting of the image used by the control from imageData in the clipboard. The message is passed unless pasteable image data is on the clipboard (in which case it's not passed).	Varies

Messages Sent

Message Sent	When Sent
stsImageWell_PreDragDrop	Sent to the control just before the dropped image is imported.
stsImageWell_DragDrop	Sent to the control after the dropped image is imported and displayed in the control.
stsImageWell_Delete	Sent to the control when the user hits the Backspace or Delete key when the stsImageWell has the focus.

Version History

Version	Release Date	What's Changed
1.1.2	06-25-2011	Fixed bug where setting the "Scale to fit" option would not "stick".
1.1.1	06-05-2011	Fixed bug where pasting an image would generate an error.
1.1	06-04-2011	First public version.