Class: Button

cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseButton
------------------------DfBasePushButton
---------------------------Button
------------------------------cCommandLinkButton
------------------------------cSplitButton

The Button class is used to create visual representations of keys or buttons that, when pressed by users, produce a specific action with an immediate response. Cancel and OK are typical uses of Buttons.

The cSplitButton class displays a split button, with an image and text on the left and a drop down image on the right.

The cCommandLinkButton class displays a command line button, with an image on the left followed by a large-text label with optional notes text underneath it in smaller text.

Sample

Object OkButton is a Button
    Set Location to 30 30
    Set Label to "&OK"
    Set Status_Help to "Print the report."    

    Procedure onClick
        Delegate Send Print_Report
    End_Procedure

End_Object

Object CancelButton is a Button
    Set Location to 30 85
    Set Label to "&Cancel"
    Set Status_Help to "Close current panel"

    Procedure onClick
        Send Close_Panel
    End_Procedure

End_Object

On_Key Key_Alt+Key_O Send KeyAction of OkButton
On_Key Key_Alt+Key_C Send KeyAction of CancelButton

Syntax

Use Windows.pkg

Object object_name is a Button
    Set Location to row column
    Set Label to text
    Set Enabled_State to True|False
    Set Status_Help to text

    Procedure onClick
        :
    End_Procedure

End_Object

On_Key Key_alt+Key_ch send KeyAction of ObjectName

Of Special Note

This class is a subclass of the DfBasePushButton class and therefore inherits all its properties and capabilities. It has been extended to support help, status help display, object shadowing, and label display.

Processing a Button Event

When a button is pressed (with the keyboard or the mouse), the event message onClick is sent. Therefore, a button will almost always contain a custom definition of the onClick message. The KeyAction message sends the onClick message if the button is active and it is enabled (enabled_state is true). This provides a simple way to bind an accelerator key to a button action. The key will do whatever the button normally does but will only do it if the button is active and enabled.

Creating Default-Action Buttons

Often a Windows panel will contain a "default" button. The action associated with this button is executed when users press the Enter key from any other non-button object within the panel. When a default button is enabled, it is visibly highlighted to indicate that pressing the Enter key will execute the button's action.

In DataFlex we refer to such a button as being the default-action button. Within a DataFlex dialog object (a view, dbView, ModalPanel, dbModalPanel, ReportView, etc.), a single default action button may be assigned. When this dialog has the focus pressing, the Enter key from within any control except another button will cause the default button's click behavior to get executed. Normally this executes the button's onClick message. A default button's border will be highlighted when it is "active" (when pressing Enter from within another object will execute the default button behavior).

A default-action button is defined by setting the desired button's default_state property to true. Only one button within a dialog may have this property set to true. Setting this to true in one button sets this property to false in all others. (Technically, this is not a property at all, but from a usage perspective it is best to think of it as such.).

Object OK_bn is a Button
    Set Label to "&Ok"
    Set Location to 115 152
    Set default_state to TRUE

    Procedure OnClick
         Send Save_Record
    End_Procedure

End_Object

Shadowing

Shadowing refers to the process of making an object or an item unavailable for data entry. Usually the appearance of a shadowed object is changed in some way to indicate its unavailability. This class supports object shadowing. Accordingly, objects of this class will be shadowed whenever an ancestor object is shadowed or when the object is explicitly shadowed by setting its enabled_state property to false.

Labels

The label of a button object refers to the text within this object.

Button Size

The default size of this object is the standard size of a Windows button (14 x 50). You only need to set the size of this object if you wish to create a non-standard-sized button.