Method XbpCrt():showModal() Foundation

Displays the XbpCrt object as a modal dialog.

Syntax
:showModal( [<oXbpFocus>] ) --> xResult
Parameters
<oXbpFocus>
Specifies the input element which receives the input focus in the dialog. The object must be derived from the XbpWindow() class, and it must be a child object of the XbpCrt window. By default, :showModal() sets the input focus to the modal dialog itself after the dialog is visible.
Return

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

Description

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

The XbpCrt window is closed by the user
The XbpCrt's default button is selected
The XbpCrt's cancel button is selected
The XbpCrt 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 XbpCrt: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 XbpCrt 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 XbpCrt 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 oCrt := SetAppWindow() 
 LOCAL oDlg 
 LOCAL oBtn 
 LOCAL nEvent, mp1, mp2, oXbp 
 LOCAL nResult 

  // 
  // Create XbpCrt object 
  // 
  oDlg := XbpCrt():new( AppDesktop(), SetAppWindow() ) 
  oDlg:title := "Modal Dialog" 
  oDlg:create() 
  oDlg:useShortCuts := .T. 

  SetAppWindow( oDlg ) 

  SetColor( "N/W+" ) 
  CLS 

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

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

  // 
  // Display the modal form 
  // 
  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 

  SetAppWindow( oCrt ) 
  WAIT 
   
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.