inkey statement/function

	<< Index >>	FutureBasic
inkey		statement / function

Syntax
[key =] inkey [%(x,y) [,] ] [prompt [, characters [, passFlag [, caseOption ]]]]]

Requires
macOS 10.12+

Description
On execution, a small floating panel appears which accepts a user keypress. Pressing any key returns a CFString containing the key's text.
The default location for the panel is 20 pixels in from the left and vertically centered on the app's front window. If there are no app windows, the panel is centered on the screen.

The prompt and (x,y) coordinate parameters are optional.

Parameters

Parameter Description

%(x,y) When this optional parameter is used, the inkey panel is positioned at point x,y relative to the top-left corner of the app's front window content area (or screen if the app does not have any open windows). If this parameter isn't specified, the inkey panel is displayed in its default location.

prompt A CFString-based message, supplied by the programmer's code, guides the user's key entry. It appears adjacent and immediately to the left of a flashing underscore.

characters A CFString of characters. This sets up formatting for the current and subsequent inkey commands. If this parameter is not specified, or is an empty string, the passFlag and caseOption parameters are ignored. A NULL value removes formatting for this and subsequent inkey commands.

passFlag A BOOL value to indicate whether to allow (pass) characters (YES) or to block them (NO). Default = YES.

caseOption Options:

_formatCaseInsensitive (0)// allow/block uppercase or lowercase characters _formatCaseSensitive // allow/block matching case characters _formatLowercase // return the entered text in lowercase _formatUppercase // return the entered text in uppercase _formatCapitalize // return the entered text capitalized

Return value
A CFStringRef containing the user-entered text. If the inkey panel was dismissed with the 'esc' key, it returns NULL.

See also
The CocoaUI header, Inkey.incl, for a list of ancillary functions.

Parameter	Description
%(x,y)	When this optional parameter is used, the inkey panel is positioned at point x,y relative to the top-left corner of the app's front window content area (or screen if the app does not have any open windows). If this parameter isn't specified, the inkey panel is displayed in its default location.
prompt	A CFString-based message, supplied by the programmer's code, guides the user's key entry. It appears adjacent and immediately to the left of a flashing underscore.
characters	A CFString of characters. This sets up formatting for the current and subsequent inkey commands. If this parameter is not specified, or is an empty string, the passFlag and caseOption parameters are ignored. A NULL value removes formatting for this and subsequent inkey commands.
passFlag	A BOOL value to indicate whether to allow (pass) characters (YES) or to block them (NO). Default = YES.
caseOption	Options: `_formatCaseInsensitive (0)// allow/block uppercase or lowercase characters _formatCaseSensitive // allow/block matching case characters _formatLowercase // return the entered text in lowercase _formatUppercase // return the entered text in uppercase _formatCapitalize // return the entered text capitalized`