Class XbpDialog() Foundation
Class function of the XbpDialog class.
The XbpDialog class provides objects that manage dialog windows. XbpDialog windows are the windows used for dialogs in pure GUI applications. XbpDialog windows differ from XbpCrt windows, in that no text oriented output (such as that performed using QOut() or @...SAY) can be performed in an XbpDialog window. A dialog window allows only graphic output and contains other dialog elements (other Xbase Parts). An XbpDialog object is the central element in pure GUI applications programmed using Xbase++.
The drawing area of an XbpDialog window
An XbpDialog object actually consists of only a frame that allows the dialog window to be enlarged or reduced. This frame contains an additional windows: the drawing area. This window is an instance of the XbpIWindow class that provides "implicit windows". An implicit window does not have a border or a title bar, but simply manages a rectangular area on the screen. The implicit window that manages the drawing area of a dialog window has special significance in programming dialogs. All Xbase Parts displayed in a dialog window must have the drawing area as the parent of the Xbase Part and not the dialog window itself. The dialog window is managed by the XbpDialog object and the drawing area is managed by an XbpIWindow object. The drawing area is contained in the instance variable :drawingArea of the XbpDialog object. If an Xbase Part is contained in a dialog window, oXbpDialog:drawingArea must always be specified as its parent.
Changing focus between XbpDialog windows
If multiple dialog windows are displayed, focus changes automatically when windows are clicked with the mouse. During a focus change at least four events are created. Note that the exact order and number of events is platform dependent. However, the last event received is always the xbeP_SetInputFocus event that denotes the change of input focus to the object.
Events sent during a focus change
Event | Description |
---|---|
xbeP_KillInputFocus | Previous focus object lost focus |
xbeP_KillDisplayFocus | Previous focus object deactivated |
xbeP_SetDisplayFocus | Dialog window activated |
xbeP_SetInputFocus | Dialog's :drawingArea got focus |
Events sent during a focus change
Event | Description |
---|---|
xbeP_KillDisplayFocus | Previous focus object deactivated |
xbeP_SetDisplayFocus | Dialog window activated |
xbeP_KillInputFocus | Previous focus object lost focus |
xbeP_SetInputFocus | Dialog got focus |
xbeP_KillInputFocus | Dialog lost focus *) |
xbeP_SetInputFocus | Dialog's :drawingArea got focus *) |
|
If a dialog window is to react to one of these events, callback code blocks must be assigned to the corresponding instance variables :killDisplayFocus :killInputFocus, :setInputFocus or :setDisplayFocus. It is important that a focus change is complete before SetAppFocus() is called again. Interrupting a focus change by calling SetAppFocus() from a callback code block can lead to unpredictable situations. In case the focus must be reset within this sequence of events for any reason, it is recommended that SetAppFocus() only be called after the xbeP_SetDisplayFocus event is retrieved with AppEvent().
XbpDialog on the OS/2 platform
Under OS/2, an XbpDialog window has a second implicit window: the title bar. It is referenced in the instance variable :titleBarArea.
XbpDialog on Windows platforms
Windows does not provide a separate implicit window for managing the title bar of an XbpDialog window. Thus, the instance variable :titleBarArea always contains NIL. For the configuration of an XbpDialog window, the instance variable :taskList plays an important role when the window is displayed on the desktop. See the description of configuration instance variables for details.
When using MDI client windows in an application, there are some particular technical features where Windows differs from OS/2 (Note: an MDI client window is created when an XbpDialog window receives as parent the :drawingArea of another XbpDialog window):
The instance variables in this group configure system resources. If changes are made to these values, they must either be made before the :create() method is executed or the :configure() method must be used to activate the changes.
// The example demonstrates parent, owner, and child
// relationships. Two dialog windows are created.
// The first dialog has the "application window"
// as its parent. The second dialog window can be
// positioned freely on the screen, because the parent
// is the desktop window. The owner is the same for
// both dialog windows and is the "application window".
// When the "application window" is minimized or moved,
// the same action is executed for both dialog windows.
// Both dialog windows include pushbuttons that control
// the dialog windows.
#include "Xbp.ch"
#include "Appevent.ch"
PROCEDURE Main
LOCAL nEvent, mp1, mp2, oXbp
LOCAL oDlg1, oDlg2, oDraw1, oDraw2, oBtn, bSetFocus, bKillFocus
SetColor("N/W")
CLS
bSetFocus := {|mp1,mp2,obj| ;
QOut( obj:title, "received the focus") }
bKillFocus := {|mp1,mp2,obj| ;
QOut( obj:title, "lost the focus") }
// Create dialog window which can only be
// positioned within the application window
oDlg1 := XbpDialog():new( ,, {50,30}, {300,200} )
oDlg1:title := "Parent is Application Window"
oDlg1:create()
oDlg1:setDisplayFocus := bSetFocus
oDlg1:killDisplayFocus := bKillFocus
oDraw1 := oDlg1:drawingArea
// Create two pushbuttons in the dialog window (children)
// The parent of the pushbuttons is :drawingArea !
oBtn := XbpPushButton():new( oDraw1 ,, {10,10}, {100,30} )
oBtn:caption := "Dialog 2"
oBtn:create()
oBtn:activate := {|| ;
IIf( oDlg2:getFrameState()==XBPDLG_FRAMESTAT_MINIMIZED, ;
oDlg2:setFrameState(XBPDLG_FRAMESTAT_NORMALIZED),NIL),;
SetAppFocus( oDlg2 ), QOut("Dialog 2") }
oBtn := XbpPushButton():new( oDraw1,, {160,10}, {100,30} )
oBtn:caption := "Maximize"
oBtn:create()
oBtn:activate := ;
{|| oDlg1:setFrameState( XBPDLG_FRAMESTAT_MAXIMIZED ) }
// Create dialog window that can be
// positioned outside the application window
oDlg2 := XbpDialog():new( ,, {400,300}, {500,300} )
oDlg2:title := "Parent is Desktop - Owner is Application"
oDlg2:create( AppDesktop(), SetAppWindow() )
oDlg2:setDisplayFocus := bSetFocus // ^ this is the owner
oDlg2:killDisplayFocus := bKillFocus
oDraw2 := oDlg2:drawingArea
// Create pushbutton that shifts the focus
// to the first dialog window
oBtn := XbpPushButton():new( oDraw2 ,, {10,10}, {100,30} )
oBtn:caption := "Dialog 1"
oBtn:create()
oBtn:activate := {|| ;
IIf( oDlg1:getFrameState()==XBPDLG_FRAMESTAT_MINIMIZED , ;
oDlg1:setFrameState(XBPDLG_FRAMESTAT_NORMALIZED), NIL), ;
SetAppFocus( oDlg1 ), QOut("Dialog 1") }
// Event loop
nEvent := 0
DO WHILE nEvent <> xbeP_Close
nEvent := AppEvent( @mp1, @mp2, @oXbp )
oXbp:handleEvent( nEvent, mp1, mp2 )
ENDDO
RETURN
// The example demonstrates how a menu can be
// constructed within a dialog window. A menu bar
// is created with only one menu item that calls
// a submenu.
#include "Appevent.ch"
PROCEDURE Main
LOCAL nEvent, mp1, mp2, oXbp
LOCAL oDlg, oMenuBar, oMenu
SetColor("N/W")
CLS
// Create dialog
oDlg := XbpDialog():new( AppDesktop() ,, ;
{30,50}, {400,250} )
oDlg:title := "Xbase++ Dialog with Menubar"
oDlg:create()
// Create XbpMenubar in the dialog
oMenuBar := oDlg:menuBar()
// Create submenu and specify the menu bar as parent
oMenu := XbpMenu():New( oMenuBar ):create()
oMenu:title := "~SubMenu"
oMenu:addItem( { "~First ", {|| QOut("First") } } )
oMenu:addItem( { "~Second", {|| QOut("Second")} } )
// Attach submenu to menu bar
oMenubar:addItem( { oMenu, NIL } )
nEvent := 0
DO WHILE nEvent <> xbeP_Close
nEvent := AppEvent( @mp1, @mp2, @oXbp )
oXbp:handleEvent( nEvent, mp1, mp2 )
ENDDO
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.