| **Navigation:**  Window and Report Control Properties >====== Button Control Properties ====== | [[box control properties.htm|{{btn_prev_n.gif|Previous page}}]][[coming future.htm|{{btn_home_n.gif|Return to chapter overview}}]][[check box control properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

A push button ([[button  declare a pushbutton control .htm|BUTTON]]) is a rectangular area containing text and/or a picture. When the user presses the button, it should execute a command described by the text or picture.

{{notebox.jpg|NoteBox.jpg}}

The Property View presents you with two ways to viewing a control's properties.

At the top of the Property View, press the categorized button {{categorized.jpg|categorized.jpg}} to view a control's properties by category (the deafult).

Or press the alphabetical button {{alphabetical.jpg|alphabetical.jpg}} to view a control's properties in alphabetical order.

This help documents displays the properties in the categorical view.

**Color**

Enter a valid color equate in the **TextColor** property or press the ellipsis (...) button to select a color from the **Color** dialog. The **Window Designer** adds the [[color  set color .htm|COLOR]] attribute to your control declaration.

Text color only affects button text when an icon is present. However, Text color always affects the focus indicator (dotted rectangle that appears when the button has focus).

See ..\LIBSRC\EQUATES.CLW for a list of valid color equates. See //Windows Design Issues// in the //User's Guide// for a discussion on using color to enhance your application.

**Design**

| **Locked** | "Freezes" the control so that subsequent data dictionary changes are not applied. You can override the #Freeze attribute for all controls or for individual controls. See **[[application options dialog.htm|Application Options]]**. |
| **Suppress Transparency**{{stbut.jpg|STBut.jpg}} | Allows the proper display of special static parent controls when populated "on top of" multiple tab controls. This property is set to TRUE by default, and ensures a proper display regardless of Visual Styles used. No effect on runtime window. |
| **Tab Index** | Determines the index in the TAB order that this control will follow. The first tab in the order is index zero (0).To change the **TabIndex** property //immediately// while in the Designer, use the **Show tab order** interface (i.e. on the right-click menu).If you set the **TabIndex** property using the property page, the z-order is not updated until you save and exit the Window Designer. |
| **UseVisualStyles** | Set to TRUE to display this control in a Visual Style appearance (as if the XP manifest was active) |

**Extra**

| **Delay** | The amount of time before the second EVENT:Accepted occurs in hundredths of seconds. The first EVENT:Accepted occurs when the end user clicks and holds the button. (The [[delay  set repeat button delay .htm|DELAY]] |
| **Drop ID** | To specify the type of Drag operations this control will accept, type up to 16 //signatures//, separated by commas. The **Window Designer** adds the **[[dropid  set drag and drop target signatures .htm|DROPID]]** attribute to the control, which indicates the control is a valid target for the drag and drop operations identified by the signatures. |
| **Icon** | In the **Icon **field, optionally select a standard icon, .BMP, or .GIF file. This displays a small bitmap on the button face (clipping or centering the bitmap as necessary). |
|  | To select a standard icon, choose one of the named items in the drop-down list. To select an icon file (whose extension must be .ICO), choose **Select File **from the drop-down list, then pick the file using the standard file dialog. |
| **Repeat** | This is how often the EVENT:Accepted occurs in hundredths of seconds when the end user clicks and holds the button. (The [[repeat  set repeat button rate .htm|REPEAT]] attribute) |
| **STD ID** | Executes a standard action when the end user presses the button. **See Also:** [[std  set standard behavior .htm|STD]] . |

**General**

| **Justification** | The **Justification **drop down list is used with button icons. **//Default//** places the icon above any text. **//Right-Justified//** places the icon to the right of any text. **//Left-Justified//** places the icon to the left of any text. |
| **Layout** | Indicates the orientation of the control. **Left to Right** maintains the original layout specified in the Window Designer. **Right to Left** essentially "flips" the controls' display as a mirror image of the layout specified in the Window Designer. Default field navigation moves from right to left. The setting in the Application Frame will cascade its setting to all child windows and controls that have the **default** setting active. |
| **Text** | The text to display on the button. Place an ampersand (&) before the character to act as the accelerator key for the button--this underlines the character as it appears on the button. |
| {{tipbox.jpg|TipBox.jpg}} | Microsoft recommends you do //not //place an accelerator key on buttons labeled 'OK,' or 'Cancel.' |
| **TextFont** | Calls the **[[select font dialog.htm|Select Font]]** dialog which lets you select the font (typeface), size, style (such as bold or italic), color, and font effects (underline and strikeout) for the selected control or window. As you choose options, the dialog box displays a sample of the selected font. |
| **Use** | This defines the [[use  set field equate label or control update variable .htm|USE]] attribute for the control. The field equate label references the button in program statements. |

**Help**

| **Alert** | Press the ellipsis to open a dialog that lets you add the [[alrt  set window  hot  keys .htm|ALRT]] attribute to a window or control. When the attribute is set, the window generates an EVENT:AlertKey if the user presses the key(s) you specify in this dialog, while the window has the focus. |
| **Cursor** | The //Cursor// field (the [[cursor  set mouse cursor type .htm|CURSOR]] attribute) lets you specify an alternate shape for the cursor when the user passes the mouse over the button. The drop-down list provides standard cursor choices such as I-Beam and Crosshair. To select an external cursor file (whose extension must be .CUR), choose **Select File **from the drop-down list, then pick the file using the standard file dialog. |
| **Help ID** | The **Help ID **field (the [[hlp  set on line help identifier .htm|HLP]] attribute) takes a string constant specifying the key for accessing a specific topic in the Help document. This may be either a Help keyword or a context string. |
|  | A Help keyword is a word or phrase indexed so that the user may search for it in the //Help //**Search **dialog. When you fill in the HLP attribute for a button, if the button has focus, when the user presses F1, the help file opens to the referenced topic. If more than one topic matches a keyword, the search dialog appears. |
|  | When referencing a context string in the **Help ID****// //**field, you must identify it with a leading tilde (~). |
| **Key** | Press the desired key or key combination (for example, CTRL+H). The keys you pressed will appear in the **Key** field, and will be supplied as parameters to the KEY or ALRT attribute for this control. The ESC, ENTER, and TAB keys //cannot// be specified by pressing them. For these keys, press the ellipsis (...) button and type "esc," "enter," or "tab." |
| **Message** | The **Message** field (the [[msg  set status bar message .htm|MSG]] attribute) lets you specify text to display in the first zone of the status bar when the control has focus. |
| **Tip** | The **[[tip  set  balloon help  text .htm|TIP]]** attribute on a control specifies the text to display in a "balloon help" box when the mouse cursor pauses over the control. Although there is no specific limit on the number of characters, the //string// should not be longer than can be displayed on the screen. |

**Mode**

| **Disable** | Disables or 'grays-out' the control when your program initially displays it. The **Window Designer** places the [[disable  set control dimmed at open .htm|DISABLE]] attribute on the control. Use the [[enable  re activate dimmed control .htm|ENABLE]] statement to allow the user access to the control. |
| **Hide** | Makes the control invisible at the time Windows would initially display it. Windows actually creates the control--it just doesn't display it on screen. The **Window Designer** places the [[hide  set control hidden .htm|HIDE]] attribute on the control. Use the [[unhide  show hidden control .htm|UNHIDE]] statement to display the control. |
| **Scroll** | Specifies whether the control should move with the window when the user scrolls the window. By default (False) the control does not move with the window. Set the **Scroll **property to False to create a control that stays fixed when the user scrolls the window. The **Window Designer** places the [[scroll  set scrolling control .htm|SCROLL]] attribute on the control when checked. |
| **Skip** | Instructs the **Window Designer** to omit the control from the Tab Order. When the user TABS from field to field in the dialog box, Windows will not give the control focus. This is useful for seldom-used data fields. The **Window Designer** will place the [[skip  set tab key skip or conditional print control .htm|SKIP]] attribute on the control. |
| **Transparent** | Specify whether you wish the control background to be **Transparent**. This instructs Windows to suppress the rectangular region around the text--the background. Normally, Windows will paint this the same uniform color as the window below the control. This adds the [[trn  set transparent control .htm|TRN]] attribute. |

**Options**

| **Default Button** | "Presses" the button when the user presses the ENTER key. A heavy border appears around the button at runtime, to signal the default button to the user. In general, place the [[default  set enter key button .htm|DEFAULT]] attribute on a button if it represents the most likely action the user will wish to carry out. Place only one default button in a window. |
| **Flat** | (the [[flat  set flat buttons .htm|FLAT]] attribute) creates a button control which appears flat until the mouse cursor passes over it. This is typically used on toolbar buttons. This feature works best if the ICON attribute names a .GIF file. |
| **Immediate** | Lets you create a button control which repeats the executable action continuously, for as long as the user holds the button down. Normally, buttons generate an event only after the user presses //and releases //the mouse. **See Also:** the [[imm  set immediate event notification .htm|IMM]] attribute. |
| **Required** | Specifies that when pressed, your program automatically checks that all entry controls with the [[req  set required entry .htm|REQ]] attribute are neither blank nor zero. A button with this attribute is a 'required fields check' button. |
|  | Specify this type of button when a window also contains an [[entry  declare a data entry control .htm|ENTRY]] or [[text  declare a multi line text control .htm|TEXT]] control field with the REQ attribute (or else use the [[incomplete  return empty req control .htm|INCOMPLETE()]] function to test the ENTRY controls). When the user presses a button with the REQ attribute and an ENTRY field is blank or zero, the first required control which is blank or zero receives the focus. |

**Position**

Lets you set the location and size of the control.

The **Position **tab lets you specify the [[at  set position and size .htm|AT]] attribute. Filling in the attribute manually is optional--you may set the position and size visually by dragging with the mouse in the **Window Designer**.

To set the location of the control's** Top Left Corner**, set an **X** (horizontal) and **Y** (vertical) coordinate in [[what is a dialog unit.htm|Dialog units]]. The coordinate is relative to the top left corner of the structure containing it, that is, the window or the report band.

To set the control's size, choose from the following options for **Width** and **Height**.

| **Default** | The Clarion runtime library determines the size of the control based on the applicable font and picture token. |
| **Full** | The control is the full height or width of the window or report. |
| **Fixed** | Lets you set a precise width or height in [[what is a dialog unit.htm|Dialog units]] on a window, or in thousandths of inch, points, or millimeters on a report. |

**Actions**

Use the Actions tab to provide functionality to your button. Filling in these prompts causes the button to execute an action when the user presses the button.

| **When Pressed** | From the drop down list, choose Call a Procedure, Run a Program, or No Special Action. |
| {{tipbox.jpg|TipBox.jpg}} | Choose No Special Action if the button is from a control template. |
|  | The procedure or program you specify executes when the user pushes the button. The choices are: |
| **Call a Procedure** | You must specify the **Procedure Name**, and whether the procedure will **Initiate a Thread**. |
| **Procedure Name** | From the **Procedure Name** drop down list, choose an existing procedure name, or type a new procedure name. A new procedure appears as a "ToDo" item in your Application Tree. |
| **Initiate a Thread** | Optionally check the **Initiate a Thread** box. If the procedure initiates a thread, specify the Thread Stack size. Clarion uses the START function to initiate a new execution thread. You can additionally specify **Parameters**, **Requested File Action**, or both. |
| {{tipbox.jpg|TipBox.jpg}} | A BUTTON on an application frame toolbar that calls an MDI child procedure __must__ initiate a thread. |
| **Thread Stack** | Accept the default value in the **Thread Stack** spin box unless you have extraordinary program requirements. To change the value, type in a new value or click on the spin box arrows. |
| **Parameters** | In the **Parameters **field, optionally type a list of variables or data structures passed to the procedure. You are limited to the number of passed parameters supported by the [[start  return new execution thread .htm|START]] statement. Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt. |
| **Requested File Action** | From the drop down list, optionally select **//None, Insert, Change, Delete//**, or **//Select//**. The default selection is **//None//**. The Global Request variable gets the selected value. The called procedure can then check the value of the Global Request variable and perform the requested file action. |
| **Run a Program** | You must specify the **Program Name**, and optionally, any parameters. |
| **Program Name** | Type the program name. The program name must be in your path or current folder, else enter the full path and executable program. Quotes are added to your entry so you don't need to enter any. |
| **Parameters** | Optionally type a list of values that are passed to the program. Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt. The variable must be preceded by an exclamation point (!). |
| **No Special Action** | Choose this option if you are providing your button's functionality with another method, such as embedded source, or an STD ID (see //Extra Tab// above). |
| {{notebox.jpg|NoteBox.jpg}} | You may combine a procedure or program call with embedded source, but not with an STD ID. |
|  |  |
| **Embeds** | Accesses the **[[gen72.htm|Embedded Source]]** dialog for points surrounding the event handling for this control only. |