Functions and Directives Functions and Directives

Function ConfirmBox() Foundation

Displays text in a graphic box and accepts user input via pushbuttons.

Syntax
ConfirmBox( [<oOwner>], <cMessage>, [<cTitle>], ;
            [<nButtons>],[<nStyle>],[<nStartBtn>] ) --> nAction
Parameters
<oOwner>
<oOwner> specifies the owner of the confirmation box. By default <oOwner> is the return value of SetAppWindow().
<cMessage>
<cMessage> is a character string containing the text to display in the confirmation box. Carriage return (Chr(13)) and line feed (Chr(10)) act as new line characters. Carriage return causes the text to be displayed on the next line and line feed on the line after that. In other words, Chr(10) first inserts a blank line.
<cTitle>
<cTitle> is a character string that is displayed in the title bar of the confirmation box. The default value is a null string ("").
<nButtons>
<nButtons> can be used to specify an optional constant from those defined in the XBP.CH file. These constants begin with XBPMB_ and specify the number of pushbuttons displayed as selections and their captions. The following constants are valid:
Constants for determining pushbuttons under OS/2
Constant Text for pushbuttons
XBPMB_OK Ok
XBPMB_OKCANCEL *) Ok and Cancel
XBPMB_RETRYCANCEL Retry and Cancel
XBPMB_ABORTRETRYIGNORE Cancel, Retry and Ignore
XBPMB_YESNO Yes and No
XBPMB_YESNOCANCEL Yes, No and Cancel
XBPMB_CANCEL Cancel
XBPMB_ENTER Enter
XBPMB_ENTERCANCEL Enter and Cancel
  1. Default value
Constants available for <nButtons> under Windows are listed in the table below:
Constants for determining pushbuttons under Windows
Constant Text for pushbuttons
XBPMB_OK Ok
XBPMB_OKCANCEL *) Ok and Cancel
XBPMB_ABORTRETRYIGNORE Abort, Retry and Ignore
XBPMB_RETRYCANCEL Retry and Cancel
XBPMB_YESNO Yes and No
XBPMB_YESNOCANCEL Yes, No and Cancel
  1. Default value
<nStyle>
<nStyle> is used to specify an optional system icon that can be selected for display to the left of the text in the confirmation box. The following constants can be used:
Constants for defining icons
Constant Icon
XBPMB_NOICON *) No icon
XBPMB_QUESTION Question mark
XBPMB_WARNING Warning
XBPMB_INFORMATION Information
XBPMB_CRITICAL Critical situation
  1. default value
In addition, the following constants for <nStyle> can be used to control the modality of the confirmation box. If a constant for an icon is used, the constants must be added to those in the following table:
Additional constants for <nStyle>
Constant Description
XBPMB_APPMODAL Confirm box is modal in relation to the Xbase++ application
XBPMB_SYSMODAL Confirm box is modal system wide
XBPMB_MOVEABLE Confirm box can be moved
<nStartBtn>
<nStartBtn> optionally specifies the pushbutton that is to have input focus immediately after the confirmation box is displayed. The following constants are valid:
Constants for the definition of focus
Constant Pushbutton
XBPMB_DEFBUTTON1 *) First pushbutton has input focus
XBPMB_DEFBUTTON2 Second pushbutton has input focus
XBPMB_DEFBUTTON3 Third pushbutton has input focus
  1. Default value
Return

The return value of ConfirmBox() is a numeric code identifying which pushbutton was pressed. Constants can be used to identify the possible return values:

Constants for the return value
Constant Description
XBPMB_RET_OK "Ok" pushbutton pressed
XBPMB_RET_CANCEL "Cancel" pushbutton pressed
XBPMB_RET_ABORT "Abort" pushbutton pressed
XBPMB_RET_RETRY "Retry" pushbutton pressed
XBPMB_RET_IGNORE "Ignore" pushbutton pressed
XBPMB_RET_YES "Yes" pushbutton pressed
XBPMB_RET_NO "No" pushbutton pressed
XBPMB_RET_ENTER "Enter" pushbutton pressed
XBPMB_RET_ERROR Confirm box could not be displayed

Description

The function ConfirmBox() allows text to be displayed in a simple, graphic dialog window and confirmation to be input by the user. This function provides only a limited number of available pushbuttons for input from the user. In most cases, these are sufficient for the user to make a decision or for the program to receive confirmation from the user.

The dialog window's size is determined by the operating system and can not be defined explicitly. If a very long text is to be displayed, this should be done using Xbase Parts (like XbpStatic or XbpMLE).

ConfirmBox() displays a simple dialog window which does not forward any messages to the Xbase++ application. This means that neither a call back method nor a call back code block is executed as long as this window has focus. In general this is only significant when a code block is assigned to the :paint call back slot or when the :paint()method of an Xbase Part is overloaded.

When a program calls this function it must be linked with /PM:PMsince ConfirmBox() displays a graphic dialog window. The function cannot be used in text mode applications.

Examples
User confirmation within a GUI application 
// The example shows how simple user confirmation can 
// be programmed using a confirm box. 

#include "Xbp.ch" 

PROCEDURE Main 
   LOCAL nButton := 0 

   DO WHILE nButton <> XBPMB_RET_YES 
      nButton := ConfirmBox( , ; 
                    "Do you want to end the program?", ; 
                    "Quit", ; 
                     XBPMB_YESNO , ; 
                     XBPMB_QUESTION+XBPMB_APPMODAL+XBPMB_MOVEABLE ) 
   ENDDO 
RETURN
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.