Xbase++ - Function XbpFromPoint()

Returns the Xbase Part residing at a certain screen position.

XbpFromPoint( <aPt>, [<lInclAll>] ) --> <oXbp> | NIL

<aPt>

<aPt> is an array of two elements which define the screen position of the Xbase Part. The position is specified relative to the coordinate system of the desktop object.

<lInclAll> is a logical value which specifies whether hidden or invisible Xbase Parts are returned by function XbpFromPoint(). The parameter defaults to .F. (false) meaning that hidden and invisible objects are ignored by this function.

The return value of XbpFromPoint() is the Xbase Part residing on the screen position specified. If no Xbase Part is found, the function returns NIL.

The function XbpFromPoint() returns the Xbase Part whose bounding rectangle encompasses a certain screen position. The position must be specified relative to the desktop. See the function AppDesktop() for further information on how to obtain the global desktop object. Also, consult the method XbpWindow:mapPoint() to learn more on how to convert a screen coordinate to a child-local coordinate and vice versa.

By default, XbpFromPoint() only respects the objects which are visible on the screen. Consequently, an Xbase Part that is marked invisible using the method XbpWindow:hide() is not returned by XbpFromPoint(). To change this behaviour, the value .T. (true) must be assigned to the <lInclAll> parameter.

XbpFromPoint() is often used in conjunction with GetPointerPos() to determine the object over which the mouse pointer resides.

Function XbpFromPoint() can only be used in GUI and Hybrid Mode applications (linker switch /PM:PM or GUI=yes in the project file).

XbpFromPoint()

// The example shows the usage of XbpFromPoint() to determine 
// whether the mouse pointer currently resides over an Xbase 
// Part. 
#include "appevent.ch" 
#include "xbp.ch" 

PROCEDURE Main() 

 LOCAL oCrt 
 LOCAL oPb 
 LOCAL nEvent 
 LOCAL mp1 := NIL, mp2 := NIL 
 LOCAL oXbp := NIL 

   SetMouse( .T. ) 
   SetColor( "N/W+" ) 
   CLS 

   // Make the console window respect standard 
   // Windows key combinations such as ALT+F4. 
   // Ensure that closing the console terminates 
   // the example. 
   oCrt := SetAppWindow() 
   oCrt:UseShortCuts := .T. 
   oCrt:Close := {|| PostAppEvent(xbeP_Quit)} 

   // Populate the console window in order to 
   // get objects to work with. Activating the 
   // push button created initiates a search 
   // for the current object using XbpFromPoint() 
   oPb := XbpPushButton():New( oCrt ) 
   oPb:Caption   := "Press SPACE..." 
   oPb:Activate  := {|| SearchXbp(GetPointerPos())} 
   oPb:Create( ,, {50,50}, {250,50} ) 

   oXbp := XbpStatic():New( oCrt ) 
   oXbp:Caption  := "Press the SPACE bar while the push button "   +; 
                    "has the input focus. This returns the Xbase " +; 
                    "Part currently under the mouse pointer. The " +; 
                    "Xbase Part is located using XbpFromPoint()." 
   oXbp:Options  := XBPSTATIC_TEXT_WORDBREAK 
   oXbp:Create( ,, {50,150}, {260,150} ) 

   oXbp := XbpListBox():New( oCrt ) 
   oXbp:Create( ,, {350,50}, {220,200} ) 

   SetAppFocus( oPb ) 

   nEvent := xbeP_None 
   DO WHILE nEvent != xbeP_Quit 
      nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
      oXbp:HandleEvent( nEvent, mp1, mp2 ) 
   ENDDO 

   oCrt:Destroy() 

RETURN 

// Check whether an Xbase Part is located at 
// the screen position passed in "aPos" 
PROCEDURE SearchXbp( aPos ) 
 LOCAL oXbp 

   oXbp := XbpFromPoint( aPos ) 
   IF oXbp == NIL 
      RETURN 
   ENDIF 

   MsgBox( "The pointer resides over an object of class " +; 
           Var2Char(oXbp:ClassName()) ) 
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.

Function XbpFromPoint() Foundation