button
Type
object
Summary
A control that is clickable.
Syntax
button
Description
Use the button object type to create a clickable button, a tabbed window, or a menu.
Button objects can be push buttons, checkboxes, radio buttons, or menus, depending on the setting of their style property.
A button whose style is set to "menu" can be a popup or contextual menu, pulldown menu, option menu, tabbed button, or combo box, depending on the setting of its menuMode property.
A button is contained in a card, group, or background. Buttons cannot contain other objects.
note
A standard button is rendered by the operating system, not LiveCode. Changing certain properties of such a button will cause the button to stop honouring the native theme. Properties that affect the button's colour and border may cause this issue.
Examples
set the hilite of button "Warning" to false
if the number of this card is 1 then hide button "Previous"
Related
command: popup
glossary: property, tabbed button, contextual menu, object type, combo box
keyword: templateButton, control, button, menu
Compatibility and Support
Introduced
LiveCode 1.0
OS
mac
windows
linux
ios
android
Platforms
desktop
server
mobile
Associated Syntax
Message
| Name | Summary | Syntax |
|---|---|---|
| socketError | Sent when an error occurs on a socket that causes the socket to close or to fail to open. | socketError <pSocketID>, <pErrorString> |
| mouseWithin | Sent periodically to an object while the mouse pointer is within its borders. | mouseWithin |
| dragEnd | Sent to the object a drag and drop started from, when the data is dropped. | dragEnd |
| focusOut | Sent to a button or field when it becomes inactive (loses focus). | focusOut |
| nameChanged | Sent to an object when its name is changed. | nameChanged <pOldName>, <pNewName> |
| dragDrop | Sent to the object where data was dropped when a drag and drop finishes. | dragDrop |
| deleteButton | Sent to a button just before it is removed from the stack. | deleteButton |
| dragLeave | Sent when the mouse pointer moves out of an object during a drag and drop. | dragLeave |
| socketTimeout | Sent when an open socket, read from socket or write to socket command halts for the time specified by the socketTimeoutInterval property. | socketTimeout <pSocketID> |
| selectedObjectChanged | Sent to an object when it is selected. | selectedObjectChanged |
| dragEnter | Sent when the mouse pointer moves into an object during a drag and drop. | dragEnter |
| mouseRelease | Sent when the user releases the mouse outside the control that was clicked. | mouseRelease <pButtonNumber> |
| mouseDown | Sent when the user presses the mouse button. | mouseDown <pButtonNumber> |
| focusIn | Sent to a control when it becomes active focused. | focusIn |
| mouseEnter | Sent when the mouse pointer moves into an object. | mouseEnter |
| menuPick | Sent to a button when a menu item is chosen from the menu associated with that button. | menuPick <pChosenItem> [, <pPreviousTab>] |
| mouseUp | Sent when the user releases the mouse button. | mouseUp <pButtonNumber> |
| dragMove | Sent when the user moves the mouse during a drag and drop. | dragMove |
| mouseStillDown | Sent periodically while the mouse button is being held down. | mouseStillDown <pButtonNumber> |
| dragStart | Sent to a control when the user clicked on it and then started to drag the mouse pointer. | dragStart |
| mouseMove | Sent when the user moves the mouse. | mouseMove <pNewMouseH>, <pNewMouseV> |
| newButton | Sent to a new button right after it's created. | newButton |
| resizeControl | Sent to a control right after the user resizes it. | resizeControl |
| mouseLeave | Sent when the mouse pointer moves out of an object. | mouseLeave |
| socketClosed | Sent when the remote system closes a socket. | socketClosed <pSocketID> |
| mouseDoubleUp | Sent when the mouse button is released at the end of a double-click. | mouseDoubleUp <pButtonNumber> |
| mouseDoubleDown | Sent when the user double-clicks. | mouseDoubleDown <pButtonNumber> |
Property
| Name | Summary | Syntax |
|---|---|---|
| topRight | Specifies the location of the specified object's upper right corner. | set the topRight of <object> to <right>, <top> |
| formattedWidth | Reports the width needed by an object to display its full contents without scrolling. | get the formattedWidth of <object> get the formattedWidth of [<chunk> of] <field> |
| script | Specifies the contents of an object's **script**. | set the script of <object> to <string> |
| borderColor | Specifies the color of an object's border. | set the borderColor of <object> to {empty | <colorName> | <RGBColor>} set the borderColor of <line> of <field> to {empty | <colorName> | <RGBColor>} |
| hilitePixel | Specifies which entry in the color table is used for the background color when an object, or text in an object, is highlighted. | set the hilitePixel of <object> to <colorNumber> |
| patterns | Specifies all the patterns of an object, in shorthand form. | set the patterns of <object> to <patternsList> |
| topMargin | Specifies how close text within an object can come to the object's upper edge, and how close objects in a group can come to the group's upper edge. | set the topMargin of {<button> | <field> | <group>} to <pixels> |
| hilitedIcon | Specifies an image to display in a button when the button is highlighted. | set the hilitedIcon of <button> to {<imageID> | <imageName>} |
| number | Specifies an object's position within a file, a card's position within a stack, or a control's layer on a card. | set the number of <card> to <number> get the number of <object> |
| topLeft | Specifies the location of the specified object's upper left corner. | set the topLeft of <object> to left,top |
| altID | Specifies an alternate ID for objects. | set the altID of <object> to <IDNumber> |
| right | Specifies how far an object's right edge is from the left edge of the window or screen. | set the right of <object> to <pixels> |
| focusPattern | Specifies the pattern used for an object's outline when it has the insertion point or is active focused. | set the focusPattern of <object> to {<patternNumber> | <imageID> | empty} |
| topPattern | Specifies the pattern used to draw a three-D object's raised edge. | set the topPattern of <object> to {<patternNumber> | <imageID> | empty} |
| acceleratorKey | Specifies a shortcut key combination for a button's mouseUp handler. | set the accel[erator]Key of <button> to {empty | <letterChar>} |
| foregroundColor | Specifies the color of object text and borders. | set the foregroundColor of <object> to {empty | <colorName> | <RGBColor>} set the foregroundColor of [<chunk> of] <field> to {empty| <colorName> | <RGBColor>} |
| text | Specifies the text contained by a button or field or the binary data in an image. | set the text of {<button> | <field> | <image>} to <string> |
| acceleratorText | Specifies the shortcut hint that appears at the right edge of a button. | set the accel[erator]Text of <button> to <string> |
| hoverIcon | Specifies an image to display in a button when the mouse pointer enters the button. | set the hoverIcon of <button> to {<imageID> | <imageName>} |
| armFill | Determines whether a button menu is drawn with a border when armed. | set the armFill of <button> to {true | false} |
| menuMouseButton | Specifies which mouse button can be used to access the menu associated with a button. | set the menuMouseButton of <button> to {zero | <pButtonNumber>} |
| borderPixel | Specifies which entry in the color table is used for the color of an object's border. | set the borderPixel of <object> to <colorNumber> |
| shadowPixel | Specifies which entry in the color table is used for the color of an object's drop shadow or the background of a scrollbar. | set the shadowPixel of <object> to <colorNumber> |
| showIcon | Specifies whether a button's icon is visible. | set the showIcon of <button> to {true | false} |
| behavior | Allows an object to inherit its script handlers from another object. | set the behavior of <object> to {<button> | <stack>} |
| customProperties | Specifies all the custom properties of an object that are in the current customPropertySet, along with their settings. | set the customProperties of <object> to <propertiesArray> set the customProperties[<propertySet>] of <object> to <propertiesArray> |
| showHilite | Specifies whether the box or circle belonging to checkboxes and radio buttons is shown. | set the showHilite of <button> to {true | false} |
| shadowColor | Specifies the color of an object's drop shadow or the background of a scrollbar. | set the shadowColor of <object> to {empty | <colorName> | <RGBColor>} |
| textSize | Specifies the point size of text displayed by an object. | set the textSize of <object> to <pointSize> set the textSize of [<chunk> of] <field> to <pointSize> |
| autoArm | Specifies whether a button becomes armed when the mouse pointer moves into it. | set the autoArm of <button> to {true | false} |
| encoding | Returns the encoding of the specified piece of text. | the encoding of { button | graphic | group } the encoding of [<chunk> of] <field> |
| shadowOffset | Specifies the size and direction of an object's drop shadow. | set the shadowOffset of <object> to <pixels> |
| visited | Specifies whether a button or grouped text has been clicked during the current session. | set the visited of <button> to {true | false} set the visited of <chunk> of <field> to {true | false} |
| textFont | Specifies the font face of text in an object. | set the textFont of <object> to <fontName> [, <language>] set the textFont of [<chunk> of] <field> to <fontName> [, <language>] |
| unicodeLabel | Specifies the UTF-16 string to be displayed on the specified object if its showName property is true. | set the unicodeLabel of object to labelString |
| mnemonic | Specifies which character of a button's name can be used with the Alt key to trigger the button. | set the mnemonic of <button> to <number> |
| hiliteBorder | Specifies whether a three-D button appears to be pushed in when it is highlighted. | set the hiliteBorder of <button> to {true | false} |
| menuMode | Determines the appearance and behavior of menus associated with a button. | set the menuMode of <button> to <menuType> |
| enabled | Specifies that an object is active and responds to user action. | set the enabled of <object> to {true | false} |
| backgroundColor | Specifies an object's background color. | set the backgroundColor of <object> to {empty | <colorName> | <RGBColor>} set the backgroundColor [of <chunk>] [of <line>] of <field> to {empty| <colorName> | <RGBColor>} |
| hiliteColor | Specifies the color of the background when an object, or text in an object, is highlighted. | set the hiliteColor [of <object>] to {empty | <colorName> | <RGBColor>} |
| dropShadow | Specifies the drop shadow to use for an object. | set the dropShadow of object to <propertiesArray> set the dropShadow[<propertyName>] of object to <propertyValue> |
| textAlign | Specifies how text is aligned or justified in a field or button. | set the textAlign [of <line>] of {<button> | <field>} to {left | center | right} |
| leftMargin | Specifies how close text within an object can come to the object's left edge, and how close objects in a group can come to the group's left edge. | set the leftMargin of {<button> | <field> | <group>} to <pixels> |
| menuHistory | Specifies the number of the currently selected item of the menu that belongs to a button. | set the menuHistory of <button> to <itemNumber> |
| bottomPattern | Specifies the pattern of a three-D object's lowered edge. | set the bottomPattern of <object> to {empty | <patternNumber> | <imageID>} |
| customPropertySets | Lists all the custom property sets that can apply to an object. | get the customPropertySets of <object> |
| hilitePattern | Specifies the fill pattern used for the background when an object, or text in an object, is highlighted. | set the hilitePattern of <object> to {<patternNumber> | <imageID> | empty} |
| visible | Specifies whether an object can be seen or is hidden. | set the [effective] visible of <object> to {true | false} |
| shadowPattern | Specifies the pattern of an object's drop shadow. | set the shadowPattern of <object> to {<patternNumber> | <imageID> | empty} |
| layer | Specifies the back-to-front order of objects on a card or the order of cards in a stack. | set the layer of <object> to {<layerNumber> | top | bottom} |
| backgroundPattern | The **backgroundPattern** specifies the pattern used to draw an object's background. | set the backgroundPattern of <object> to {<patternNumber> | <imageID> | empty} |
| topColor | Specifies the color of a three-D object's raised edge. | set the topColor of <object> to {empty | <colorName> | <RGBColor>} |
| bottom | Specifies how far an object's bottom edge is from the top of the window or screen. | set the bottom of <object> to <number> |
| borderPattern | Specifies the pattern of an object's border. | set the borderPattern of <object> to {empty | <patternNumber> | <imageID>} |
| colorOverlay | Specifies the color overlay to use for an object. | set the colorOverlay of object to <propertiesArray> set the colorOverlay[<propertyName>] of object to <propertyValue> |
| hilite | Determines whether a button is highlighted. | set the hilite of <button> to {true | false} |
| height | Specifies the distance from an object's top edge to its bottom edge. | set the height of <object> to <numberOfPixels> |
| armedIcon | Specifies an image to display in a button when the mouse pointer enters it. | set the armedIcon of <button> to {<imageID> | <imageName>} |
| menuLines | Specifies the number of visible lines in a drop-down list menu belonging to a button. | set the menuLines of <button> to <number> |
| outerGlow | Specifies the outer glow to use for an object. | set the outerglow of object to <propertiesArray> set the outerglow[<propertyName>] of object to <propertyValue> |
| bottomPixel | Specifies which entry in the color table is used for the color of a three-D object's lowered edge. | set the bottomPixel of <object> to <colorNumber> |
| sharedHilite | Specifies whether a grouped button's hilite property is the same on all cards with that group. | set the sharedHilite of <button> to {true | false} |
| traversalOn | Specifies whether a control can become the active (focused) control. | set the traversalOn of <object> to {true | false} |
| titleWidth | Specifies the amount of a button's width used to display the button's name or label property to the left of the button. | set the titleWidth of <button> to <pixels> |
| acceleratorModifiers | Specifies one or more modifier keys that must be pressed with the button shortcut key specified by the acceleratorKey property. | set the acceleratorModifiers of <button> to {empty | <keys>} |
| top | Specifies how far an object's top edge is from the top of the window or screen. | set the top of <object> to <numberOfPixels> |
| rectangle | Specifies the area within which an object is drawn. | set the rectangle of <object> to <left>, <top>, <right>, <bottom> get the [effective] rectangle of <object> |
| invisible | Specifies whether an object is hidden. | set the invisible of <object> to {true | false} get the [effective] invisible of <object> |
| layerMode | Specifies whether an object is dynamic or static. | set the layerMode of <object> to <mode> get the [effective] layerMode of <object> |
| topPixel | Specifies which entry in the color table is used for the color of a three-D object's raised edge. | set the topPixel of <object> to <colorNumber> |
| bottomRight | Specifies the location of the specified object's lower right corner. | set the bottomRight of <object> to right,bottom |
| armed | Specifies whether a button has a changed (active) appearance due to the mouse pointer moving into it | set the armed of <button> to {true | false} |
| foregroundPixel | Specifies which entry in the color table is used for an object's text and borders. | set the foregroundPixel of <object> to <colorNumber> |
| unicodeTooltip | Specifies the explanatory text (UTF-16 string) that pops up in a small box when the user points to an object. | set the unicodeTooltip of object to <unicodeString> |
| bottomLeft | Specifies the location of the specified object's lower left corner. | set the bottomLeft of <object> to <left>, <bottom> |
| innerShadow | Specifies the inner shadow to use for an object. | set the innerShadow of object to <propertiesArray> set the innerShadow[<propertyName>] of object to <propertyValue> |
| label | Specifies the string shown in a stack window's title bar, or a text label to be displayed on the specified object if its showName property is true. | set the label of <object> to <labelString> |
| location | Specifies where an object is. | set the location of <object> to <point> |
| left | Specifies how far an object's left edge is from the left edge of the window or screen. | set the left of <object> to <numberOfPixels> |
| showFocusBorder | Displays a border around the active control. | set the showFocusBorder of <control> to {true | false} |
| unicodeText | Specifies the text in a field, represented as Unicode (double-byte characters). | set the unicodeText of [<chunk> of] <field> to <unicodeString> set the unicodeText of <button> to <unicodeString> |
| disabled | Specifies that an object is dimmed and does not respond to user action. | set the disabled of <object> to {true | false} |
| penBack | Has no effect and is included in LiveCode for compatibility with imported SuperCard projects. | set the penBack [of <object>] to <colorNumber> |
| rightMargin | Specifies how close text within an object can come to the object's right edge, and how close objects in a group can come to the group's right edge. | set the rightMargin of {<button> | <field> | <group>} to <pixels> |
| iconGravity | Specifies wether the icon of a button is placed independently of the label. | set the iconGravity of <button> to <position> |
| selected | Specifies whether an object is **selected**. | set the selected of <object> to {true | false} |
| hiliteFill | Specifies whether a button's background is filled with the hiliteColor and hilitePattern when the button is highlighted. | set the hiliteFill of <button> to {true | false} |
| properties | Specifies some of an object's **properties** and their current values. | set the properties of <object> to <propertiesArray> |
| visitedIcon | Specifies an image to display in a button when the button's visited property is true. | set the visitedIcon of <button> to {<imageID> | <imageName>} |
| colors | Specifies all the colors of an object, in shorthand form. | set the colors of <object> to <colorsList> |
| ID | Reports the unique ID number assigned to an object. | set the ID of {image | stack} to <number> get the [{ long | abbreviated | short }] ID of <object> |
| autoHilite | Specifies whether a button highlights when it's pressed, or whether selected text in a field is highlighted. | set the autoHilite of {<button> | <field>} to {true | false} |
| customPropertySet | Specifies a set of custom properties applied to an object. | set the customPropertySet of object to {setName | empty} |
| disabledIcon | Specifies an image to display in a button when the button is disabled. | set the disabledIcon of <button> to {<imageID> | <imageName>} |
| backgroundPixel | Specifies which entry in the color table is used for an object's background color. | set the backgroundPixel of <object> to <colorNumber> |
| menuName | Specifies the stack where the menu associated with a button is located. | set the menuName of <button> to <stack> |
| style | Specifies the general appearance and behavior of an object. | set the style of <object> to <styleName> |
| focusPixel | Specifies which entry in the color table is used for the color of an object's outline when it has the insertion point or is active focused. | set the focusPixel of <object> to <colorNumber> |
| bottomColor | Specifies the color of a three-D object's lowered edge. | set the bottomColor of <object> to {empty | <colorName> | <RGBColor>} |
| bottomMargin | Specifies how close text within an object can come to the object's lower edge, and how close objects in a group can come to the group's lower edge. | set the bottomMargin of {<button> | <field> | <group>} to <pixels> |
| textStyle | Specifies the style or styles applied to text in an object. | set the textStyle of <object> to {empty | plain | <stylesList>} set the textStyle of [<chunk> of] <field> to {empty | plain | <stylesList>} set the textStyle[<style>] of object to {true | false} |
| threeD | Specifies whether an object appears to stick out of or recede into the screen. | set the threeD of <object> to {true | false} |
| width | The **width** of an object is the distance from its left edge to its right edge. | set the width of <object> to <numberOfPixels> |
| showBorder | Specifies whether an outline is drawn around an object. | set the showBorder of <object> to {true | false} |
| innerGlow | Specifies the inner glow to use for an object | set the innerGlow of object to <propertiesArray> set the innerGlow[<propertyName>] of object to <propertyValue> |
| name | Specifies the name of an object. | set the [{ long | abbreviated | short }] name of <object> to <string> get the name |
| owner | Reports which object is next in the object hierarchy. | get the [{ long | abbreviated | short }] owner of <object> |
| armBorder | Determines whether a button is drawn with a border when armed. | set the armBorder of <button> to {true | false} |
| default | Specifies that a button will be automatically chosen when the user presses Return or Enter. | set the default of <button> to {true | false} |
| showName | Specifies whether an object's name is displayed within it. | set the showName of {<button> | <graphic> | <group>} to {true | false} |
| formattedHeight | Reports the height needed by an object to display its full contents without scrolling. | get the formattedHeight of <object> get the formattedHeight of [<chunk> of] <field> |
| focusColor | Specifies the color of the outline around the active control or the field with the insertion point. | set the focusColor of <object> to {empty | <colorName> | <RGBColor>} |
| customKeys | Lists the names of all the custom properties of an object. | set the customKeys of <object> to {<propertiesList> | empty} |
| family | Coordinates a set of radio buttons so that only one button of a family can be highlighted. | set the family of <button> to <number> |
| foregroundPattern | Specifies the pattern used for object text and borders. | set the foregroundPattern of <object> to {<patternNumber> | <imageID> | empty} set the foregroundPattern of [<chunk> of] <field> to {<patternNumber> | <imageID> | empty} |