Confirm - cUIObject

Pops up a "Yes/No" confirmation

Type: Function
Return Data Type: Integer

Parameters

Parameter	Type	Description
item_name	String	The question to be presented

Syntax

Function Confirm String item_name Returns Integer

Call Example

Get Confirm item_name to IntegerVariable

Description

The Confirm function can be used to pop up a "Yes/No" confirmation. When called, it pops up a Windows Yes/No message box. The message-box caption will be Confirm and it will present the passed question, allowing users to select the Yes or No button. The syntax for using the function is as follows:

Get Confirm QuestionString to ReturnValue

This can be used at any point in your program and provides a very easy method to ask a "Yes/No" question. For example:

Procedure Run_Report
    Integer iFail

    Get Confirm "Print Aged Balance Report Now?" to iFail
    If Not (iFail) Begin
        Send Start_Report of oAgedTeport
    End
End_Procedure

The confirm package is defined in the DFConFrm.pkg and is automatically included in DFAllEnt.pkg. You do not need to explicitly "use" it. This means that confirm and message box support are "built right in there" as a resource.

User Confirmations and Queries Overview

Most of the time, your program runs in a non-modal state. Users may choose to navigate and enter data in the order of their choosing. There are times when you need the program to stop this user-driven system, pop up a dialog panel, ask a question, and based on the answer, take an action. There are several ways to create and use modal popup objects. If you need to ask a (Yes/No" question, you should use the Confirm package, which is documented in this section. If you require a different response (e.g., Yes/No/Cancel), or you need a series of responses, you could use the message box, or you could create your own modal panel.

Other Confirmation Messages

There are specialized versions of the Confirm message that are used to handle specific data entry requirements. Those messages are Save_Confirmation, Delete_Confirmation, Line_Save_Confirmation, Line_Delete_Confirmation, Data_Loss_Confirmation, Exit_Loss_Confirmation, and No_Confirmation.

Sending Confirmations Automatically

Data Entry Objects (DEOs) send confirmation messages during important data-entry operations (saves, deletes, clears, exiting). This gives the program a chance to secure confirmation of critical operations from users. Each DEO class has properties that determine what confirmation message is sent for each of these operations.

These messages are usually functions. If the function returns a zero value, the confirmation passed. If it returns a non-zero value, the confirmation failed. You can use these confirmation functions to pop up a confirmation dialog box asking a particular question (e.g., Save this Record?). The popup confirmation is a standard windows message box which allows the user to respond by pressing Yes or No. After a response, the confirmation panel will disappear and the function will return a zero (yes) or non-zero (no) value according to the response from the operator.

The DfConfrm.pkg package creates objects to provide such capabilities. It also creates a number of functions that allow you to use these objects. This includes a general-purpose confirmation function (where you pass the question to be asked) and a series of pre-defined confirmation functions.

A DEO needs to know what verification message it should send during a save, delete, clear and exit. Each DEO has properties that contain the message number to be sent for the appropriate verification. These verification properties are Verify_Save_msg, Verify_Delete_msg, Verify_Data_Loss_msg and Verify_Exit_msg. If the values of one of these properties is zero, the DEO will delegate and use the message definition in its parent DEO. If the parent's property value is zero (and all of its DEO ancestors are also zero), no message will be sent.

All you need to do is to assign the appropriate function messages in DfConFrm.pkg to the appropriate DEO-verify message. The function messages available are listed below.

Sending Confirmations Manually

You can send confirmation messages manually. This is useful if you need to send these messages under conditions that your DEO does not normally handle. Below is an example of directly calling a DEO function. In this example, we want the standard save message (Save this Record?) to only be sent when a new record is saved. When an edited record is saved, we want the save to proceed without confirmation. We would augment the DEO's request_save procedure to handle this.

// This assumes that this DEO's Verify_Save_Msg is set to no_confirmation.
//
Procedure Request_Save
    Boolean bHasRec bChanged
    Integer iStat iServer

    // get current record in server. If 0, it is new.
    Get Server to iServer // the DDO we are using
    Get HasRecord of hoSrvr to bHasRec
    Get Should_Save to bChanged // is the DDO changed?
    // if a new record and there are changes confirm the save.
    If ( Not(bHasRec) AND Not(bChanged) ) Begin  // no rec
        Get Save_Confirmation to iStat // OK=0
        If (iStat) Procedure_Return      // non-zero=TRUE=not OK, exit
    End
    // Normal save will not perform a confirmation
    Forward Send Request_Save
End_Procedure  // Request_Save

The Confirm Function with DEOs

You can send custom confirmation prompts by using the confirm function. It requires that you pass it the prompt to be displayed. The following example shows how you could use the confirm function to make the above example prompt, Save this NEW record?

Procedure Request_Save
    Boolean bHasRec bChanged
    Integer iStat iServer

    Get Server to iServer
    Get HasRecord of hoSrvr to bHasRec
    Get Should_Save to bChanged
    // if a new record and there are changes confirm the save.
    If ( Not(bHasRec) AND Not(bChanged) ) Begin  // no rec
        Get Confirm "Save this NEW record?" to iStat // OK=0
        If (iStat) Procedure_Return      // non-zero=TRUE=not OK, exit
    End
    Forward Send Request_Save
End_Procedure  // Request_Save

You can also use the confirm message to create custom confirmations for a DEO or new confirmations for all DEOs. If we wanted to change an entry form's save prompt to Save this Order?, we would augment the verify_save procedure in the entry-form object:

Set Verify_Save_Msg to (RefFunc(Verify_Save)) // normal save hook

// Create custom Verify_Save for this ONE object.
Function Verify_Save Returns Integer
    Integer iRetVal

    Get Confirm "Save this Order?" to iRetVal
    Function_Return iRetVal
    // Here is an alternate method that would combine the above
    // three commands into a single command.
    //
    // Function_Return (Confirm(Self,"Save this Order?"))
    //
End_Function

When we create a verify_save function in a DEO, we are changing the behavior of the one DEO. We could also use confirm to create a new confirm message that all objects could use. We would do this by creating the new function FOR BaseClass (which really means for all classes). We would then assign a DEO's verify message to that new function. The following would allow us to create a "California-style" save message:

Function Verify_Save_California_Style FOR BasClass Returns Integer
    Integer iNoWayDude

    Get Confirm "Save this record, Dude?" to iNoWayDude
    Function_Return iNoWayDude
End_Function

Your DEO would use this prompt by placing the following in your DEO:

Set Verify_Save_Msg to (RefFunc(Verify_Save_California_Style))

Using the Confirm Package

It is very easy to hook DEOs into confirmation messages. Your program must first include the DfConfrm object package (which is included, by default, in DFAllent.pkg). Each DEO should contain code that looks like the following:

Set Verify_Save_msg to (RefFunc(Save_Confirmation))
Set Verify_Delete_msg to (RefFunc(Delete_Confirmation))
Set Verify_Data_Loss_msg to (RefFunc(Data_Loss_Confirmation))
Set Verify_Exit_msg to (RefFunc(Exit_Loss_Confirmation))

By default the dbView class defines the above confirmations as their default. The dbGrid class changes the save confirmation (to disable the confirmation -(RefFunc(No_Confirmation))) and the delete confirmation (to ask for a line delete confirmation - (RefFunc(Line_Delete_Confirmation))). You would only need to change a class or object if you needed to change these defaults.

You are encouraged to create your own confirm package. This could contain different or additional prompts. You might also want to create your own custom DEO subclasses that contain the prompts that you always want to appear in your programs. The following example would create a custom dbView subclass that always verifies saves, deletes, and clears, but does not verify, exits:

Class dbView_xyz is a dbView

    Procedure Construct_Object
        Forward Send Construct_Object

        Set Verify_Save_msg to (RefFunc(Save_Confirmation))
        Set Verify_Delete_msg to (RefFunc(Delete_Confirmation))
        Set Verify_Data_Loss_msg to (RefFunc(Data_Loss_Confirmation))
        Set Verify_Exit_msg to (RefFunc(Exit_Loss_Confirmation))
    End_Procedure

End_Class

When your confirm logic is placed in subclasses that all objects use, your programs will no longer need to set the properties in each DEO and you will be assured that all of your DEOs will behave consistently. This will also make it very easy to add more-sophisticated verification capabilities to all of your objects. It shouldn't be too hard to create classes that allow confirmations to be turned on and off at the user level.

Return Value

Returns 0 if the response is yes, 1 if the response is no.