<doc>
  <legacy_id>2111</legacy_id>
  <name>backgroundPattern</name>
  <type>property</type>
  <syntax>
    <example>set the backgroundPattern of <i>object</i> to {<i>patternNumber</i> |<i> imageID</i> | empty}</example>
  </syntax>
  <library></library>
  <objects>
    <stack/>
    <card/>
    <group/>
    <field/>
    <button/>
    <graphic/>
    <scrollbar/>
    <player/>
    <image/>
  </objects>
  <synonyms>
    <synonym>backPattern</synonym>
    <synonym>fillPat</synonym>
  </synonyms>
  <classification>
    <category>Appearance &amp; Positioning</category>
  </classification>
  <references>
    <property tag="shadowPattern">shadowPattern Property</property>
    <property tag="patterns">patterns Property</property>
    <property tag="foregroundPattern">foregroundPattern Property</property>
    <property tag="opaque">opaque Property</property>
    <property tag="metal">metal Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="1.1"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>The <b>backgroundPattern</b> specifies the pattern used to draw an <glossary tag="object">object's</glossary> background.</summary>
  <examples>
    <example>set the backgroundPattern of this card to 544</example>
    <example>set the backgroundPattern of me to the ID of image "Fill"</example>
  </examples>
  <description>
    <p>Use the <b>backgroundPattern</b> <glossary tag="property">property</glossary> to specify the pattern used for the background on which an <keyword tag="image">image</keyword> appears, or the pattern used to draw an <glossary tag="object">object</glossary>.</p><p/><p><b>Value:</b></p><p>The <b>backgroundPattern</b> of an <glossary tag="object">object</glossary> is a pattern specifier.</p><p>A <i>patternNumber</i> is a built-in pattern number between 1 and 164. (These patterns correspond to LiveCode's built-in patterns 136 to 300.)</p><p>An <i>imageID</i> is the ID of an <keyword tag="image">image</keyword> to use for a pattern. LiveCode looks for the specified <keyword tag="image">image</keyword> first in the <glossary tag="current stack">current stack</glossary>, then in other open <function tag="stacks">stacks</function>.</p><p/><p>By default, the <b>backgroundPattern</b> for all <glossary tag="object">objects</glossary> is empty.</p><p/><p><b>Comments:</b></p><p>Pattern images can be color or black-and-white.</p><p/><p><img src="202652"/> <b>Cross-platform note:</b> To be used as a pattern on <glossary tag="Mac OS">Mac OS systems</glossary>, an <keyword tag="image">image</keyword> must be 128x128 <property tag="pixels">pixels</property> or less, and both its <property tag="height">height</property> and <property tag="width">width</property> must be a power of 2, however, in LiveCode version 2.7, this restriction was partially lifted and the engine will tile rectangular regions correctly with arbitrarily sized background patterns.To be used on <function tag="openStacks">Windows</function> and <glossary tag="Unix">Unix systems</glossary>, <property tag="height">height</property> and <property tag="width">width</property> 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.</p><p/><p>The <b>backgroundPattern</b> of <glossary tag="control">controls</glossary> is drawn starting at the <glossary tag="control">control's</glossary> upper left corner: if the <keyword tag="control">control</keyword> is moved, the pattern does not shift.</p><p/><p>Setting the <b>backgroundPattern</b> of an <glossary tag="object">object</glossary> to empty allows the <b>backgroundPattern</b> of the object's <property tag="owner">owner</property> to show through. Use the <keyword tag="effective">effective</keyword> <glossary tag="keyword">keyword</glossary> to find out what pattern is used for the <glossary tag="object">object</glossary>, even if its own <b>backgroundPattern</b> is empty.</p><p/><p>The setting of the <b>backgroundPattern</b> <glossary tag="property">property</glossary> has different effects, depending on the <glossary tag="object type">object type</glossary>:</p><p>* The <b>backgroundPattern</b> of a <object tag="stack">stack</object> or <keyword tag="card">card</keyword> fills the entire <glossary tag="stack window">stack window</glossary>, as well as determining the <b>backgroundPattern</b> of each <glossary tag="object">object</glossary> in the <object tag="stack">stack</object> or <keyword tag="card">card</keyword> that does not have its own <b>backgroundPattern</b>.</p><p/><p><img src="202652"/> <b>Cross-platform note:</b> On <glossary tag="Mac OS">Mac OS</glossary>, <glossary tag="OS X">OS X</glossary>, and <glossary tag="Windows">Windows systems</glossary>, if the <b>backgroundColor</b> and <property tag="backgroundPattern">backgroundPattern</property> of all <glossary tag="object">objects</glossary> in the <glossary tag="object hierarchy">object hierarchy</glossary> is empty, the background set by the system is used.</p><p/><p>* The <b>backgroundPattern</b> of a <command tag="group">group</command> determines the <b>backgroundPattern</b> of each <glossary tag="object">object</glossary> in the <command tag="group">group</command> that does not have its own <b>backgroundPattern</b>.</p><p/><p>* The <b>backgroundPattern</b> of a <keyword tag="button">button</keyword> fills the area inside the <glossary tag="button">button's</glossary> outline. If the button's <property tag="style">style</property> is "checkbox", the <b>backgroundPattern</b> fills the checkbox. If the <glossary tag="button">button's</glossary> style is "radioButton", the <b>backgroundPattern</b> has no effect. If the <keyword tag="button">button</keyword> is a <glossary tag="tabbed button">tabbed button</glossary>, the <b>backgroundPattern</b> fills the tab area and the frontmost tab, but does not affect the other tabs.</p><p/><p><img src="202652"/> <b>Cross-platform note:</b> If the <property tag="lookAndFeel">lookAndFeel</property> is set to "Appearance Manager", standard and rectangle <glossary tag="button">buttons</glossary> are drawn by the operating system if the <property tag="backgroundColor">backgroundColor</property> and <b>backgroundPattern</b> of the <keyword tag="button">button</keyword> is empty. Otherwise, the <keyword tag="button">button</keyword> is drawn by LiveCode. If the <property tag="lookAndFeel">lookAndFeel</property> is "Appearance Manager", <glossary tag="button menu">button menus</glossary> whose <property tag="menuMode">menuMode</property> is set to "option" or "comboBox" are always drawn by the operating system, and the setting of the <b>backgroundPattern</b> does not affect them.</p><p/><p>* The <b>backgroundPattern</b> of a <keyword tag="field">field</keyword> fills the area inside the <glossary tag="field">field's</glossary> outline and (if the <keyword tag="field">field</keyword> is a scrolling <keyword tag="field">field</keyword>) the arrow boxes at the ends of the scrollbar. If you set the <b>backgroundPattern</b> of a <glossary tag="chunk">chunk</glossary> of a <keyword tag="field">field</keyword> (on <glossary tag="Unix">Unix</glossary> systems), only that <glossary tag="chunk">chunk</glossary> is affected.</p><p/><p>* The <b>backgroundPattern</b> of a <keyword tag="scrollbar">scrollbar</keyword> fills the arrow boxes at the ends of the <keyword tag="scrollbar">scrollbar</keyword>.</p><p/><p>* The <b>backgroundPattern</b> of a <keyword tag="graphic">graphic</keyword> is displayed inside the <glossary tag="graphic">graphic's</glossary> border if the <glossary tag="graphic">graphic's</glossary> fill <glossary tag="property">property</glossary> is true. If the <glossary tag="graphic">graphic's</glossary> fill is false, the setting of the <b>backgroundPattern</b> has no effect.</p><p/><p>* The <b>backgroundPattern</b> of an <glossary tag="EPS">EPS object</glossary> fills the <glossary tag="object">object's</glossary> rectangle.</p><p/><p>* The <b>backgroundPattern</b> of an <keyword tag="image">image</keyword>, <glossary tag="audio clip">audio clip</glossary>, <glossary tag="video clip">video clip</glossary>, or <keyword tag="player">player</keyword> has no effect.</p><p/><p>If an object's <b>backgroundPattern</b> is set, the pattern is shown instead of the color specified by <property tag="backgroundColor">backgroundColor</property>.</p><p/><p><b>Changes:</b></p><p>The ability to use the system background pattern was introduced in version 1.1. In previous versions, if the <b>backgroundColor</b> and <b>backgroundPattern</b> of all <glossary tag="object">objects</glossary> in the <glossary tag="object hierarchy">object hierarchy</glossary> was empty, a light gray color was used.</p>
  </description>
</doc>