|
| 1 | +--- |
| 2 | +name: Titanium.UI.iOS.ButtonConfiguration |
| 3 | +summary: | |
| 4 | + A configuration object for customizing the appearance and behavior of a button. |
| 5 | +description: | |
| 6 | + The ButtonConfiguration API provides a modern way to configure buttons on iOS with support for |
| 7 | + various styles, titles, subtitles, images, and padding. This API wraps the native `UIButtonConfiguration` |
| 8 | + introduced in iOS 15.0 and represents a modern alternative to the existing Button API while retaining |
| 9 | + backwards compatibility. In the future, this API may be merged into the root parameters of a button instead. |
| 10 | + |
| 11 | + Use the <Titanium.UI.iOS.createButtonConfiguration> method to create a button configuration. |
| 12 | + |
| 13 | + Button configurations support several predefined styles: |
| 14 | + - **plain**: A plain button style with minimal background |
| 15 | + - **tinted**: A tinted button style with a subtle background |
| 16 | + - **filled**: A filled button style with a solid background |
| 17 | + - **gray**: A gray button style |
| 18 | + - **borderless**: A borderless button style |
| 19 | + - **bordered**: A bordered button style with an outline |
| 20 | + - **borderedTinted**: A bordered button style with a tinted outline |
| 21 | + - **borderedProminent**: A bordered button style with a prominent appearance |
| 22 | + |
| 23 | + Additional styles available on iOS 26.0+: |
| 24 | + - **glass**: A glass-like appearance |
| 25 | + - **prominentGlass**: A prominent glass-like appearance |
| 26 | + - **clearGlass**: A clear glass-like appearance |
| 27 | + - **prominentClearGlass**: A prominent clear glass-like appearance |
| 28 | +
|
| 29 | +extends: Titanium.Proxy |
| 30 | +platforms: [iphone, ipad, macos] |
| 31 | +since: {iphone: "13.0.0", ipad: "13.0.0", macos: "13.0.0"} |
| 32 | +osver: {ios: {min: "15.0"}} |
| 33 | + |
| 34 | +properties: |
| 35 | + - name: style |
| 36 | + summary: The style of button configuration to create. |
| 37 | + description: | |
| 38 | + Sets the base configuration style for the button. This property should be set first |
| 39 | + as it determines the initial configuration that other properties will modify. |
| 40 | + |
| 41 | + Valid string values are: |
| 42 | + - `"plain"`: A plain button style with minimal background |
| 43 | + - `"tinted"`: A tinted button style with a subtle background |
| 44 | + - `"filled"`: A filled button style with a solid background |
| 45 | + - `"gray"`: A gray button style |
| 46 | + - `"borderless"`: A borderless button style |
| 47 | + - `"bordered"`: A bordered button style with an outline |
| 48 | + - `"borderedTinted"`: A bordered button style with a tinted outline |
| 49 | + - `"borderedProminent"`: A bordered button style with a prominent appearance |
| 50 | + - `"glass"`: A glass-like appearance (iOS 26.0+) |
| 51 | + - `"prominentGlass"`: A prominent glass-like appearance (iOS 26.0+) |
| 52 | + - `"clearGlass"`: A clear glass-like appearance (iOS 26.0+) |
| 53 | + - `"prominentClearGlass"`: A prominent clear glass-like appearance (iOS 26.0+) |
| 54 | + type: String |
| 55 | + availability: creation |
| 56 | + |
| 57 | + - name: title |
| 58 | + summary: The title text to display on the button. |
| 59 | + type: String |
| 60 | + |
| 61 | + - name: subtitle |
| 62 | + summary: The subtitle text to display below the title. |
| 63 | + type: String |
| 64 | + |
| 65 | + - name: backgroundColor |
| 66 | + summary: The background color of the button. |
| 67 | + description: | |
| 68 | + Sets the base background color for the button. This color may be modified |
| 69 | + by the system based on the button state and configuration style. |
| 70 | + type: [String, Titanium.UI.Color] |
| 71 | + |
| 72 | + - name: color |
| 73 | + summary: The foreground color of the button's content. |
| 74 | + description: | |
| 75 | + Sets the base foreground color for the button's title and subtitle text. |
| 76 | + This color may be modified by the system based on the button state. |
| 77 | + type: [String, Titanium.UI.Color] |
| 78 | + |
| 79 | + - name: image |
| 80 | + summary: The image to display on the button. |
| 81 | + description: | |
| 82 | + The image to display alongside the button's title. Use the imagePlacement |
| 83 | + property to control where the image appears relative to the title. |
| 84 | + type: [String, Titanium.Blob, Titanium.Filesystem.File] |
| 85 | + |
| 86 | + - name: padding |
| 87 | + summary: The padding around the button's content. |
| 88 | + description: | |
| 89 | + An object with top, left, bottom, and right properties to specify |
| 90 | + the content insets for the button. |
| 91 | + type: Padding |
| 92 | + |
| 93 | + - name: imagePlacement |
| 94 | + summary: The placement of the image relative to the title. |
| 95 | + description: | |
| 96 | + Controls where the button's image appears relative to its title text. |
| 97 | + |
| 98 | + Valid string values are: |
| 99 | + - `"leading"`: Place the image before the title text |
| 100 | + - `"trailing"`: Place the image after the title text |
| 101 | + - `"top"`: Place the image above the title text |
| 102 | + - `"bottom"`: Place the image below the title text |
| 103 | + type: String |
| 104 | + default: "leading" |
| 105 | + |
| 106 | + - name: imagePadding |
| 107 | + summary: The spacing between the image and title. |
| 108 | + description: | |
| 109 | + The amount of spacing in points between the button's image and its title text. |
| 110 | + type: Number |
| 111 | + default: 0 |
| 112 | + |
| 113 | + - name: titlePadding |
| 114 | + summary: The spacing between the title and subtitle. |
| 115 | + description: | |
| 116 | + The amount of spacing in points between the button's title and subtitle text. |
| 117 | + type: Number |
| 118 | + default: 0 |
| 119 | + |
| 120 | + - name: font |
| 121 | + summary: Font to use for the button title. |
| 122 | + description: | |
| 123 | + Sets the font applied to the configuration’s title via the underlying |
| 124 | + `UIButtonConfiguration.titleTextAttributesTransformer`. |
| 125 | +
|
| 126 | + When using `attributedString`, prefer setting font in the attributed content instead. |
| 127 | + type: Font |
| 128 | + |
| 129 | + - name: textAlign |
| 130 | + summary: Text alignment of the configuration title. |
| 131 | + description: | |
| 132 | + Aligns the title within the button’s content area. Maps to |
| 133 | + `UIButtonConfigurationTitleAlignment`. |
| 134 | + type: [String, Number] |
| 135 | + constants: Titanium.UI.TEXT_ALIGNMENT_* |
| 136 | + |
| 137 | + - name: attributedString |
| 138 | + summary: Specify an attributed string for the button title. |
| 139 | + description: | |
| 140 | + Sets the configuration’s `attributedTitle`. If set, avoid also setting |
| 141 | + `title`, `color`, and `font` to prevent conflicting styles. |
| 142 | + type: Titanium.UI.AttributedString |
| 143 | + |
| 144 | + - name: backgroundSelectedColor |
| 145 | + summary: Background color to use while the button is highlighted (pressed). |
| 146 | + description: | |
| 147 | + When this configuration is assigned to a <Titanium.UI.Button> and both |
| 148 | + `backgroundColor` and `backgroundSelectedColor` are provided, the button will |
| 149 | + automatically swap the configuration’s background to `backgroundSelectedColor` |
| 150 | + when highlighted and restore the base color when not highlighted. |
| 151 | +
|
| 152 | + This mirrors the traditional `backgroundSelectedColor` behavior on views when |
| 153 | + used with modern button configurations. |
| 154 | + type: [String, Titanium.UI.Color] |
| 155 | + |
| 156 | +examples: |
| 157 | + - title: Basic Button Configuration |
| 158 | + example: | |
| 159 | + ``` js |
| 160 | + const button = Ti.UI.createButton({ |
| 161 | + configuration: Ti.UI.iOS.createButtonConfiguration({ |
| 162 | + style: 'filled', |
| 163 | + title: 'Sign In', |
| 164 | + subtitle: 'with your account', |
| 165 | + backgroundColor: '#007AFF', |
| 166 | + color: 'white' |
| 167 | + }) |
| 168 | + }); |
| 169 | + ``` |
| 170 | + |
| 171 | + - title: Button with Image and Padding |
| 172 | + example: | |
| 173 | + ``` js |
| 174 | + const button = Ti.UI.createButton({ |
| 175 | + configuration: Ti.UI.iOS.createButtonConfiguration({ |
| 176 | + style: 'borderedTinted', |
| 177 | + title: 'Upload', |
| 178 | + image: 'upload-icon.png', |
| 179 | + imagePlacement: 'leading', |
| 180 | + imagePadding: 8, |
| 181 | + padding: { |
| 182 | + top: 12, |
| 183 | + left: 20, |
| 184 | + bottom: 12, |
| 185 | + right: 20 |
| 186 | + } |
| 187 | + }) |
| 188 | + }); |
| 189 | + ``` |
| 190 | + |
| 191 | + - title: Prominent Button Style |
| 192 | + example: | |
| 193 | + ``` js |
| 194 | + const button = Ti.UI.createButton({ |
| 195 | + configuration: Ti.UI.iOS.createButtonConfiguration({ |
| 196 | + style: 'borderedProminent', |
| 197 | + title: 'Get Started', |
| 198 | + backgroundColor: '#34C759' |
| 199 | + }) |
| 200 | + }); |
| 201 | + ``` |
| 202 | +
|
| 203 | + - title: Typography and Alignment |
| 204 | + example: | |
| 205 | + ``` js |
| 206 | + const button = Ti.UI.createButton({ |
| 207 | + configuration: Ti.UI.iOS.createButtonConfiguration({ |
| 208 | + style: 'filled', |
| 209 | + title: 'Continue', |
| 210 | + font: { fontSize: 18, fontWeight: 'semibold' }, |
| 211 | + textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER |
| 212 | + }) |
| 213 | + }); |
| 214 | + ``` |
| 215 | +
|
| 216 | + - title: Highlighted Background Color |
| 217 | + example: | |
| 218 | + ``` js |
| 219 | + const button = Ti.UI.createButton({ |
| 220 | + configuration: Ti.UI.iOS.createButtonConfiguration({ |
| 221 | + style: 'filled', |
| 222 | + title: 'Tap Me', |
| 223 | + backgroundColor: '#007AFF', |
| 224 | + backgroundSelectedColor: '#005BBB' // shown while pressed |
| 225 | + }) |
| 226 | + }); |
| 227 | + ``` |
0 commit comments