AcceptText

Description

Applies the contents of the DataWindow's edit control to the current item in the buffer of a DataWindow control or DataStore. The data in the edit control must pass the validation rule for the column before it can be stored in the item.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object


Syntax

PowerBuilder

integer dwcontrol.AcceptText ( )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow


Return value

Returns 1 if it succeeds and -1 if it fails (for example, the data did not pass validation).

If there is no DataWindow object assigned to the DataWindow control or DataStore, this method returns 1.

Usage

When a user moves from item to item in a DataWindow control, the control validates and accepts data the user has edited.

How to call AcceptText

When a user modifies a DataWindow item then immediately changes focus to another control in the window, the DataWindow control does not accept the modified data -- the data remains in the edit control. Use the AcceptText method in this situation to ensure that the DataWindow object contains the data the user edited.

However, you must not call AcceptText in the LoseFocus event or in a user event posted from LoseFocus if the DataWindow control still has focus. If you do, an infinite loop can occur.

The problem

Normally, new data is validated and accepted when the user moves to a new cell in the DataWindow. If the new data causes an error, a message box displays, which causes the DataWindow to lose focus. If you have also coded the LoseFocus event or an event posted from LoseFocus to call AcceptText to validate data when the control loses focus, this AcceptText runs because of the message box and triggers an infinite loop of validation errors.

The solution

It is desirable to validate the last changed data when the control loses focus. You can accomplish this by making sure AcceptText gets called only when the DataWindow control really has lost focus. The third PowerBuilder example illustrates how to use an instance variable to keep track of whether the DataWindow control has focus. The posted event calls AcceptText only when the DataWindow control does not have focus.

This is a change from previous versions of PowerBuilder. Previously, the posted user event would run while the message box for the validation error was displayed. Now, it runs after the message box is dismissed, causing another validation error to occur and another message box to be displayed, resulting in an infinite loop.

Events

AcceptText can trigger an ItemChanged or an ItemError event.

AcceptText in the ItemChanged event

Calling AcceptText in the ItemChanged event has no effect.

Examples

In this example, the user is expected to enter a key value (such as an employee number) in a column of the DataWindow object, then click the OK button. This script for the Clicked event for the button calls AcceptText to validate the entry and place it in the DataWindow control. Then the script uses the item in the Retrieve method to retrieve the row for that key:

IF dw_emp.AcceptText() = 1 THEN
      dw_emp.Retrieve(dw_emp.GetItemNumber &
         (dw_emp.GetRow(), dw_emp.GetColumn()))
END IF

This script for the Clicked event for a CommandButton accepts the text in the DataWindow dw_Emp and counts the rows in which the column named balance is greater than 0:

integer i, Count
dw_employee.AcceptText()
FOR i = 1 to dw_employee.RowCount()
      IF dw_employee.GetItemNumber(i,'balance') &
            > 0 THEN
         Count = Count + 1
      END IF
NEXT

This example illustrates how to validate newly entered data when the DataWindow control loses focus. An instance variable keeps track of whether the DataWindow control has focus. It is set in the GetFocus and LoseFocus events. The LoseFocus event posts the ue_acceptText event, which calls the AcceptText method only if the DataWindow control does not have focus.

The instance variable:

boolean dw_has_focus

The GetFocus event:

dw_has_focus = true

The LoseFocus event:

dw_has_focus = false
dw_1.event  post ue_acceptText( )

The ue_acceptText event:

IF dw_has_focus = false THEN
      dw_1.accepttext( )
END IF

See also

Update