Method XbpDialog():showModal()

Displays the XbpDialog object as a modal dialog.

:showModal( [<oXbpFocus>] ) --> xResult

Specifies the input element which is to receive the input focus in the dialog. The object must be derived from the XbpWindow() class, and it must be a child object of the dialog. By default, :showModal() sets the input focus to the modal dialog itself after the dialog is visible.

This method returns the result of the modal dialog. This is the value assigned to the :modalResult instance variable.

The method :showModal() displays an XbpDialog object as a modal form. Contrary to the :show() method, :showModal() does not terminate until one of the following conditions is met:

The dialog is closed by the user

The dialog's default button is selected

The dialog's cancel button is selected

The dialog object is hidden by application code

A value other than XBP_MRESULT_NONE is assigned to the :modalResult instance variable

The method :showModal() is ideal for showing dialogs designed to return a result of a certain kind. These dialogs typically have an Ok and Cancel push button and must be closed by the user before being able to work with other dialogs of the application. Internally, :showModal() uses the method XbpWindow:setModalState()to disable the Xbase Part specified in parameter <oOwner>to method :new() or :create().

The method :showModal() uses an internal event loop that dispatches events while the modal XbpDialog window is being displayed. The event loop ensures that the application continues to function, even though its standard event loop is not executed until :showModal() returns. The event loop executes until the user either closes the XbpDialog object using its close, default or cancel buttons, or if the application terminates the dialog by assigning a result value to the instance variable :modalResult. See the documentation on :modalResult for further information. Also see the :default and :cancel instance variables of the XbpPushbutton class to learn more about defining default buttons for a modal dialog.

 // 
 // Example for using :showModal() 
 // 
 #include "AppEvent.CH" 
 #include "XBP.CH" 

 PROCEDURE Main() 
  LOCAL oDlg 
  LOCAL oBtn 
  LOCAL nResult 

   // 
   // Create application's main dialog 
   // 
   oDlg := XbpDialog():new( Appdesktop() ) 
   oDlg:title 	  := "Modal Dialog Example" 
   oDlg:taskList := .T. 
   oDlg:close    := {|| PostAppEvent(xbeP_Quit,,, oDlg) } 
   oDlg:create( ,, {50,50}, {600,400},, .F. ) 

   // 
   // Create default push buttons ("Ok" and 
   // "Cancel") 
   // 
   oBtn  := XbpPushButton():new( oDlg:drawingArea ) 
   oBtn:caption := "Ok" 
   oBtn:default := .T. 
   oBtn:tabStop := .T. 
   oBtn:create( ,, {360,20},{100,30} ) 

   oBtn  := XbpPushButton():new( oDlg:drawingArea ) 
   oBtn:caption := "Cancel" 
   oBtn:cancel  := .T. 
   oBtn:tabStop := .T. 
   oBtn:create( ,, {470,20},{100,30} ) 

   // 
   // Display the modal dialog 
   // 
   nResult := oDlg:showModal() 

   DO CASE 
      CASE nResult == XBP_MRESULT_OK 
         Msgbox( "The Ok button was pressed." ) 
      CASE nResult == XBP_MRESULT_CANCEL 
         Msgbox( "You cancelled the dialog." ) 
   ENDCASE 
    
   oDlg:destroy() 
 RETURN 

 // Overloaded AppSys() procedure to prevent 
 // creation of the default XbpCrt window 
 PROCEDURE AppSys() 
 RETURN

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.

Method XbpDialog():showModal() Foundation