Name: focusPattern

Type: property

Syntax: set the focusPattern of <object> to {<patternNumber> | <imageID> | empty}

Summary: Specifies the pattern used for an <object|object's> outline when it has the <insertion point> or is <active (focused)(glossary)>.

Associations: stack,card,field,button,graphic,scrollbar,player,image

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,mobile

Example:
set the focusPattern of this stack to 2215

Value:
The <focusPattern> of an <object> is a pattern specifier.
A <patternNumber> is a built-in pattern number between 1 and 164. (These patterns correspond to LiveCode's built-in patterns 136 to 300.)

An <imageID> is the ID of an <image> to use for a pattern. LiveCode looks for the specified <image> first in the <current stack>, then in other open <stacks>.

By default, the <focusPattern> for all <object|objects> is empty.

Description:
Use the <focusPattern> <property> to specify the pattern used for the outline around an <active (focused) control(glossary)>.

Pattern images can be color or black-and-white.

>*Cross-platform note:*  To be used as a pattern on <Mac OS|Mac OS systems>, an <image> must be 128x128 <pixels> or less, and both its <height> and <width> must be a power of 2. To be used on <Windows> and <Unix|Unix systems>, <height> and <width> must be divisible by 8. To be used as a fully cross-platform pattern, both an image's dimensions should be one of 8, 16, 32, 64, or 128.

The <focusPattern> of <control(object)|controls> is drawn starting at the <control(object)|control's> upper right corner: if the <control(keyword)> is moved, the pattern does not shift.

Setting the <focusPattern> of an <object> to empty allows the <focusPattern> of the <object|object's> <owner> to show through. Use the <effective> <keyword> to find out what color is used for the <object>, even if its own <focusPattern> is empty.

The setting of the <focusPattern> <property> has different effects, depending on the <object type>:

* The <focusPattern> of a <stack>, <card>, or <group> determines the <focusPattern> of each <object> in the <stack>, <card>, or <group> that does not have its own <focusPattern>.

* The <focusPattern> of a <button(keyword)> is used to outline the <button(keyword)> when it is <focus|focused>. If the <button(object)|button's> <style> is menu, or if the button's <traversalOn> <property> is false, the <focusPattern> has no effect.

* The <focusPattern> of a <field> or <scrollbar> is used to outline the <object> when it is <focus|focused>. If the object's <traversalOn> <property> is false, the <focusPattern> has no effect.

* The <focusPattern> of a <graphic>, <image>, <player>, <audioClip>, <videoClip>, or <EPS|EPS object> has no effect.

If an object's <focusPattern> is set, the pattern is shown instead of the color specified by the <focusColor>.

The <focusPattern> <property> has no effect if the <lookAndFeel> <property> is set to Macintosh<a/>.

References: effective (keyword), field (keyword), image (keyword), button (keyword), card (keyword), scrollbar (keyword), player (keyword), graphic (keyword), control (keyword), pixels (property), owner (property), height (property), style (property), width (property), focusColor (property), lookAndFeel (property), traversalOn (property), focus (command), group (command), videoClip (object), button (object), control (object), object (object), stack (object), audioClip (object), property (glossary), EPS (glossary), Windows (glossary), object type (glossary), insertion point (glossary), focus (glossary), Mac OS (glossary), keyword (glossary), active control (glossary), Unix (glossary), current stack (glossary), stacks (function)

Tags: ui
