Function GraCaptionStr() | Xbase++

Functions and Directives Functions and Directives

Draws a caption.

GraCaptionStr( [<oPS>],    <aStartPoint>, [<aEndPoint>], ;
               <cCaption>, [<nAlign>], [<nTabChars>]  ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space in which the caption 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 positioning the caption. 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.

[<aEndPoint>] := { <nXEnd>, <nYEnd> }

<aEndPoint> is an array of two elements. Together with <aStartPoint>, the coordinates specified in <aEndPoint> define a rectangle to be used for aligning the caption. This parameter is optional.

If parameter <nAlign> is used to request text alignment other than the default (XBPALIGN_LEFT + XBPALIGN_VCENTER), the application must pass a value for the parameter <aEndPoint>. Otherwise, text alignment may be incorrect.

[<cCaption>]

A character string displayed as a caption.

[<nAlign>]

An optional numeric value that specifies how the caption is to be aligned within the rectangle defined by <aStartPoint>and <aEndPoint>. The application may pass a combination of the following constants to specify text alignment:

Constant	Description
XBPALIGN_TOP	Align caption at the top
XBPALIGN_LEFT *)	Align caption on the left
XBPALIGN_BOTTOM	Align caption at the bottom
XBPALIGN_RIGHT	Align caption on the right
XBPALIGN_HCENTER	Center caption horizontally
XBPALIGN_VCENTER *)	Center caption vertically
XBPALIGN_WORDBREAK	Text is wrapped in (multi-line)
Default value

XBPALIGN_WORDBREAK is a special option which causes text to be wrapped into several lines. Carriage Return (Chr(13)) and Line Feed (Chr(10)) are used to determine where the line breaks should occur. Carriage Return characters cause the text to be displayed on the next line and Line Feed characters cause the display to skip to the line after the next. In other words, the line feed (Chr(10)) inserts a blank line. Selecting option XBPALIGN_WORDBREAK implicitly causes the text to be displayed at the top of the display rectangle. Changing the vertical text alignment is no longer possible.

[<nTabChars>]

Optional parameter that controls how the tab character is expanded if present in the character string. If a tab is found, it is substituted by the number of spaces specified in the <nTabChars> parameter. The default value for this parameter is 8.

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

The function GraCaptionStr() draws a character string within the rectangle defined by the <aStartPoint> and <aEndPoint>parameters. If <aEndPoint> is not specified, the function GraQueryTextBox() is used to compute a default rectangle. GraCaptionStr() uses the text rectangle to align the caption according to the text alignment specified in parameter <nAlign>. If the text is to be right-aligned, for example, the string is positioned at the right-hand border of the text rectangle.

If tab characters (Chr(9)) are present in the character string, they are expanded to the number of space characters specified in <nTabChars>. GraCaptionStr() also recognizes the shortcut character "~" (tilde). If such a shortcut character is defined in the caption, the character following the tilde is shown underlined.

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

If a Micro PS is passed in argument <oPS>, GraCaptionStr() respects a Visual Style set for the Xbase Part which executed the method :LockPS(). In addition, the caption string is rendered with respect to the state of the object. See instance variable XbpWindow:controlState for further information.

If the parameter <nAlign> is used to specify an alignment other than the default, an array should be passed in <aEndPoint>. Otherwise, the caption may not be aligned as requested.

Windows 9x,ME: GraCaptionStr() does not respect a transform set using method XbpPresSpace:setGraTransform().

Function GraCaptionStr() Foundation