Functions and Directives

Function GraSegPriority() Foundation

Changes priority of a graphic segment in relation to a second segment.

GraSegPriority( [<oPS>], <nSegmentA>, <nSegmentB>, ;
                         <nPriority> ) --> lSuccess
The argument <oPS> specifies the presentation space where the priority of a graphic segment is changed. If the current window is an XbpCrt window, <oPS> is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created using XbpPresSpace():new(). A "Micro PS" cannot be used for this function.
<nSegmentA> is the segment ID for the graphic segment whose priority is changed. The segment ID is returned by the function GraSegOpen().
<nSegmentB> is the segment ID for the graphic segment which serves as the comparison segment for reprioritizing <nSegmentA>.
The parameter <nPriority> specifies one of the two #define constants GRA_SEG_LOWER_PRI ( <nSegmentA> receives lesser priority) or GRA_SEG_HIGHER_PRI ( <nSegmentA> receives higher priority).

The return value of GraSegPriority() is .T. (true) when the priority for the segment <nSegmentA> was changed, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined using GraError().


The priority of graphic segments determines the order in which the segments are drawn. It is comparable with the z axis in the three dimensional coordinate system. When GraSegDraw() is called, the segment with the lowest priority is drawn first and the segment with the highest priority is drawn last. If segments overlap, the segments with lower priority are painted over by segments with higher priority.

When the value 0 is specified for the comparison segment <nSegmentB>, <nSegmentA> receives either the highest or lowest priority of all segments depending on whether GRA_SEG_LOWER_PRI or GRA_SEG_HIGHER_PRI was used for <nPriority>.

Setting segment priorities
// In the example three different colored segments are drawn. 
// By a left mouse click in a segment the priority of that 
// segment is set to highest priority so that the 
// clicked segment is brought to the foreground. 

#include "" 
#include "" 
#include "" 

   LOCAL nBox1, nBox2, nArc, aAttr, aColor, bSetColor, i 
   LOCAL aSegment, aFound, mp1, mp2, nEvent := xbe_None 

                                    // area attributes for 
   aAttr := Array( GRA_AA_COUNT )   // circle and box 
                                    // code block to change color 
   bSetColor := {|nColor| aAttr [ GRA_AA_COLOR ] := nColor, ; 
                          GraSetAttrArea( NIL, aAttr ) } 
                                    // graphic mouse coordinates 
   SetAppWindow():mouseMode := XBPCRT_MOUSEMODE_PM 
   SetMouse(.T.)                    // activate mouse 

   aSegment := {} 

   AAdd( aSegment, GraSegOpen( NIL, GRA_SEG_MODIFIABLE ) ) 
   Eval( bSetColor, aColor[1] )     // create segments (red box) 
   GraBox( NIL, { 80,120}, {200,200}, GRA_OUTLINEFILL ) 

   AAdd( aSegment, GraSegOpen( NIL, GRA_SEG_MODIFIABLE ) ) 
   Eval( bSetColor, aColor[2] )     // green box 
   GraBox( NIL, {150, 70}, {330,150}, GRA_OUTLINEFILL ) 

   AAdd( aSegment, GraSegOpen( NIL, GRA_SEG_MODIFIABLE ) ) 
   Eval( bSetColor, aColor[3] )     // blue circle 
   GraArc( NIL, {120,100},  80,,,, GRA_OUTLINEFILL ) 

   DO WHILE nEvent <> xbeM_RbClick  // cancel with right mouse click 

      nEvent := AppEvent( @mp1, @mp2,,0 ) 

      IF nEvent == xbeM_LbDown              // left mouse click 
         aFound := GraSegFind( NIL, mp1 )   // searches segment 

         @ MaxRow(),0 SAY Space(80) 

         IF ! Empty( aFound )               // bring first segment 
                                            // found to the 
                                            // foreground 
            GraSegPriority( NIL, aFound[1], 0, GRA_SEG_HIGHER_PRI ) 
            GraSegDraw( NIL, aFound[1] )    // draw new segment 

            SetPos( MaxRow(), 0 )           // display IDs of 
            Aeval( aFound, {|n| QQout(n)} ) // segments found 



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.