Functions and Directives Functions and Directives

Function GraFocusRect() Foundation

Draws a rectangle using imagery that denotes input focus.

Syntax
GraFocusRect( [<oPS>], [<aStartPoint>], [<aEndPoint>] ) --> lSuccess
Parameters
<oPS>
The argument <oPS> specifies the presentation space in which the focus rectangle is drawn. 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 either by using XbpPresSpace():new() or a "Micro PS" must be requested from an Xbase Part using the method:lockPS(). After graphic output is complete, the Micro PS must be released with :unlockPS().
<aStartPoint> := { <nXStart>, <nYStart> }
<aStartPoint> is an array of two elements which determines the coordinates for the origin of the focus rectangle. The first element <nXStart>specifies the x coordinate and the second element <nYStart>specifies the y coordinate. The unit for the coordinates depends on the coordinate system defined for the presentation space. If no presentation space is defined, the values for the coordinates are given in pixels, which is the unit for a window.
The Parameter <aStartPoint> is optional whenever a Micro Presentation Space is passed in <oPS>. If <aStartPoint> is omitted, the origin of the focus rectangle is set to the lower-left corner of the corresponding Xbase Part. Note that if a Visual Style is used with the Xbase Part, the start point given in <StartPoint> may be offset by an amount defined within the style.
<aEndPoint> := { <nXEnd>, <nYEnd> }
<aEndPoint> is an array of two elements which contains the coordinates of the end point of the rectangle.
The Parameters <aEndPoint> is optional whenever a Micro Presentation Space is passed in <oPS>. If this parameter is omitted, the end point of the rectangle corresponds to the upper-left corner of the Xbase Part. Note that if a Visual Style is applied to the Xbase Part, the end point may be offset by an amount defined within the style.
Return

The return value of GraFocusRect() is .T. (true) if the rectangle is drawn, otherwise it is .F. (false).

Description

The function GraFocusRect() is a graphic primitive which draws a rectangle in a presentation space. The rectangle is rendered using the default imagery for rectangles that denote input focus. GraFocusRect() draws in XOR mode. This means that a focus rectangle can be removed from the screen by executing GraFocusRect() again using identical call parameters.

The function GraFocusRect() is intended primarily for usage with Micro Presentation Spaces. It cannot be used in graphic segments. Furthermore, GraFocusRect() neither uses nor updates the current cursor position.

On Windows 2000 and newer, the focus rectangle is displayed only if visual focus indicators (visual cues) are permanently enabled, or if the user currently works with the keyboard. Depending on system configuration, no output may be produced by GraFocusRect(), if input is currently made solely with the mouse. See the method XbpWindow:IsUICueActive()for further information.

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.