Clarion Community Help

Navigation: Window and Report Control Properties >====== Button Control Properties ======

A push button (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.

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 to view a control's properties by category (the deafult).

Or press the alphabetical button 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 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.
Suppress Transparency	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
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 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 attribute)
STD ID	Executes a standard action when the end user presses the button. See Also: 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.
	Microsoft recommends you do not place an accelerator key on buttons labeled 'OK,' or 'Cancel.'
TextFont	Calls the 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 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 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 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 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 attribute) lets you specify text to display in the first zone of the status bar when the control has focus.
Tip	The 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 attribute on the control. Use the 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 attribute on the control. Use the 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 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 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 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 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 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 attribute.
Required	Specifies that when pressed, your program automatically checks that all entry controls with the 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 or TEXT control field with the REQ attribute (or else use the 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 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 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 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.
	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.
	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 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).
	You may combine a procedure or program call with embedded source, but not with an STD ID.

Embeds	Accesses the Embedded Source dialog for points surrounding the event handling for this control only.