Class XbpDialog() Foundation

Class function of the XbpDialog class.

Superclass
Description

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.

XbpDialog windows implicitly set the input focus on the object referenced in their :drawingArea property upon activation.

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 *)
  1. Events required to set input focus to the :drawingArea

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):

If an XbpDialog window is to receive MDI client windows, it must have a menubar installed (see the method :menuBar()).
MDI client windows cannot have their own menubar.
It is not possible to create nested MDI client windows.
It is not possible to create an MDI client window with fixed size. The size of an MDI client window can always be changed by the user.
Class methods
:new()
Creates an instance of the XbpDialog class.
Configuration

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.

:alwaysOnTop
Determines whether the dialog window can be covered by other dialogs.
:clipChildren
Determines whether the Xbase Parts in the child list are clipped during graphic output.
:border
Border type for the dialog window.
:gridMove
Restricts the movement of the window to increments of :fontWidthwhen the mouse is used to move the window.
:hideButton
Displays the pushbutton to "hide" a dialog window.
:icon
The resource ID of an icon.
:maxButton
Displays the pushbutton for maximizing the dialog window.
:minButton
Displays the pushbutton for minimizing the dialog window.
:moveWithOwner
Moves the dialog window when the owner is moved.
:origin
Sets the origin of the coordinate system for the dialog window.
:sysMenu
Determines whether to include the system menu in the title bar of the dialog window.
:taskList
Determines whether the XbpDialog window is included as an item in the task list.
:title
Title of the XbpDialog window
:titleBar
Determines whether the title bar of the XbpDialog window is displayed.
Runtime data
:clientSize
Specifies the dimensions of the dialog inner area (drawing area).
:hasDisplayFocus
Specifies whether the dialog currently is the active window.
:modalResult
Specifies the result of a modal dialog.
:drawingArea
The window for the drawing area of the dialog window.
:maxSize
Sets the maximum size for the dialog window.
:minSize
Sets the minimum size for the dialog window.
:titleBarArea
The window for the title bar of the XbpDialog window.
Life cycle
:create()
Requests system resources for the XbpDialog object.
:configure()
Reconfigures the XbpDialog object after :create() has been executed.
:destroy()
Releases the system resources of the XbpDialog object.
Methods
:showModal()
Displays the XbpDialog object as a modal dialog.
:calcClientRect()
Returns the inside dimensions of a dialog window.
:calcFrameRect()
Returns the outside dimensions of the dialog window.
:getFrameState()
Determines the current display state of the dialog window.
:getTitle()
Returns the title of the XbpDialog window.
:hasMenuBar()
Specifies whether the XbpDialog object has a menu bar.
:menuBar()
Installs an XbpMenubar object in the XbpDialog window.
:setFrameState()
Sets the display state of the XbpDialog window.
:setTitle()
Defines a new title for the XbpDialog window.
Events
:close
Dialog window is being closed.
:keyboard
Keyboard input received.
:killDisplayFocus
XbpDialog window is losing display focus.
:setDisplayFocus
XbpDialog window receives the display focus.
Examples
Parent, owner and child relationships for dialog windows

// 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 
Dialog window with menu

// 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 
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.