stsSearchBox

Version 1.0

Sons of Thunder Software, Inc.

Description

The DropTool provides a search box widget that looks like the one in OS X or Windows Vista/7. You can respond to the user's search criteria after each letter they type (optional) or when they hit the Return or Enter keys. You can also choose to show a text prompt in the search box or not (if you show it, it goes away as soon as you click in the field).

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.

Extra Features

	"About" Stack
	"Inspector" Stack

Screenshots

Mac OSX

Windows

Usage Notes

When the user enters text in the search field and hits the Enter or Return key, a message is sent to the control so you can trap it and perform your search. You can also get the message sent after each character is typed, so you can implement an "instant" (or "type-to-match") search.

You also have the option of providing a text prompt that can be displayed in the search box that goes away when the user clicks in the search field.

Here's an example of how to use it. Suppose you had a list of food items and you wanted to allow the user to filter the list based on their search text. You could script the control group this way:

Custom Properties

Property	Possible Values	Notes
uSTSPrompt	Any string, or empty	Indicates what prompt to show in the search box. Set it to empty to not show a prompt at all. Defaults to the string "Search".
uSTSSearchByChar	"true" or "false"	Determines whether the stsSearchBox_Search message is sent after every character is typed ("true") or if it is sent only after the user hits Return or Enter ("false").

Commands/Functions

These commands must be "sent" to the instance of the control or triggered from the script of the control itself.

Command	Parameters	Notes
stsSearchBox_Init	(none)	Resets the control to its original state, and adjusts the UI to correspond to the current platform.
stsSearchBox_HideCancel	(none)	Hides the Cancel button portion of the control. You should only need to call this if you decide to trap the stsSearchBox_Cancel message (see below).

Messages Sent

Message Sent	When Sent
stsSearchBox_Cancel	Sent to the control when the user clicks the Cancel button. Make sure to pass this message otherwise the cancelling is not processed (you'd have to clear out the text in the field and hide the cancel button yourself).
stsSearchBox_Search pTextToFind	Sent to the control after each key is typed by the user (if the uSTSSearchByChar of the control is "true"), or after the user hits the Return or Enter key (if the uSTSSearchByChar of the control is "false"). pTextToFind is the text that is in the Search box.