Compute_Text_Extent

Functions

void Compute_Text_Extent (const char *segment, const char *text, float *xfrac, float *yfrac)
 Finds out what the dimensions are for a given text string. More...
 
void Compute_Text_Extent_By_Key (HC_KEY key, float *xfrac, float *yfrac)
 Similar to Compute_Text_Extent(), but operates on text referenced by an HC_KEY. More...
 
void Compute_Text_Extent_By_Path (int count, const HC_KEY *keys, const char *text, float *xfrac, float *yfrac)
 Similar to Compute_Text_Extent(), but concatenates the matrices along a segment path rather than the currently open segment. More...
 
void Compute_Text_Extent_Enc_Path (int count, const HC_KEY *keys, const char *encoding, const char *text, float *xfrac, float *yfrac)
 Similar to Compute_Text_Extent_By_Path(), but operates on encoded text rather that Latin1 text. More...
 
void Compute_Text_Extent_With_Enc (const char *segment, const char *encoding, const char *text, float *xfrac, float *yfrac)
 Similar to Compute_Text_Extent() but operates on encoded text rather than Latin1 text. More...
 

Detailed Description

Function Documentation

◆ Compute_Text_Extent()

void Compute_Text_Extent ( const char *  segment,
const char *  text,
float *  xsize,
float *  ysize 
)

Finds out what the dimensions are for a given text string.

Parameters
segment- The segment whose attributes (or net attributes) will be applied to the problem.
text- The text string whose extent is to be tested.
xsize- The size of the text in the X direction. Returned to the user. Passed by reference always.
ysize- The size of the text in the Y direction. Returned to user. Passed by reference always.

DETAILS

Unlike most geometry, the size of text depends on a complicated concatenation of attributes, and figuring it out from first principles is not straightforward. Compute_Text_Extent() performs the calculation for you. The returned value for xsize and ysize will be a fraction from 0.0 to 1.0 (or more) of the segment's window.

Once you have the text extent, it can be used, for example, to build a small bounding box around text that's being used for string input (to limit the scope of screen updates). Or to lay out a popup menu big enough for the contained text. Or to wrap a highlight line around text.

If you use the text extent numbers to lay out windows, you usually need to multiply xfrac and yfrac by two to convert to a window distance, since windows range from -1 to +1. For example, to build a subwindow at the lower-left of the currently-open segment that's just big enough to hold a "rabbit", you might do the following:

                Compute_Text_Extent (".", "rabbit", &xfrac, &yfrac)
                Open_Segment ("")
                        Set_Window (-1., -1. + 2*xfrac, -1., -1. + 2*yfrac)
                        Insert_Text (0., 0., 0., "rabbit")
                Close_Segment ()

For text with the transforms option enabled via Set_Text_Font(), the xsize and ysize values will be returned in object relative units (oru) instead of the usual screen relative units.

NOTES

In versions prior to 16.0, the extent returned included a small amount of white space all around. Now, the default behavior for Compute_Text_Extent returns the exact extent for the specified text. To revert to the behavior displayed by Compute_Text_Extent prior to 16.0, you can turn on the legacy text extent option in Define_System_Options.

This compute function does not include descenders or ascenders, such as accents over capitals letters, in the extent calculations.

The device will be "started" if necessary for the Info routines to work. See Show_Font_Info() for details.

Any reference in your program to Compute_Text_Extent_With_Enc() will cause the Kanji font data to be linked. This may increase the size of your executable image.

Compute_Text_Extent_With_Enc() looks odd because it's been truncated at 31 characters.

RESTRICTIONS

The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. This specifically includes Compute_Text_XXX() routines. Display information must be associated with a window to return information about the display.

Calling Compute_XXX() routines to obtain data associated with a display generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment. The application calls the compute routine, retains the computed information, and then discards the temporary driver subsegment.

See also
Show_Net_Text_Font, Show_Net_Text_Path, Show_Net_Text_Alignment, Show_Device_Info, Show_Font_Info, Show_Text, Show_Text_Encoding, Compute_Coordinates, Compute_Transform

◆ Compute_Text_Extent_By_Key()

void Compute_Text_Extent_By_Key ( HC_KEY  key,
float *  xfrac,
float *  yfrac 
)

Similar to Compute_Text_Extent(), but operates on text referenced by an HC_KEY.

Parameters
key- Key of the text on which the computation is to be done.
xfrac- The fraction from 0.0 to 1.0 (or more), in the X direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac- The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.

DETAILS

No additional details. See Compute_Text_Extent()

◆ Compute_Text_Extent_By_Path()

void Compute_Text_Extent_By_Path ( int  count,
const HC_KEY *  keys,
const char *  text,
float *  xfrac,
float *  yfrac 
)

Similar to Compute_Text_Extent(), but concatenates the matrices along a segment path rather than the currently open segment.

Parameters
count- The size of the keys array
keys- The array of keys starting with the owning segment and following
all the way back to the root segment or other desired segment.
text- The text string whose extent is to be tested.
xfrac- The fraction from 0.0 to 1.0 (or more), in the X direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac- The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.

DETAILS

No additional details. See Compute_Text_Extent()

◆ Compute_Text_Extent_Enc_Path()

void Compute_Text_Extent_Enc_Path ( int  count,
const HC_KEY *  keys,
const char *  encoding,
const char *  text,
float *  xfrac,
float *  yfrac 
)

Similar to Compute_Text_Extent_By_Path(), but operates on encoded text rather that Latin1 text.

Parameters
count- The size of the keys array
keys- The array of keys starting with the owning segment and following
all the way back to the root segment or other desired segment.
encoding- The encoding method used for text.
text- The text string whose extent is to be tested.
xfrac- The fraction from 0.0 to 1.0 (or more), in the X direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac- The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.

DETAILS

No additional details. See Compute_Text_Extent()

◆ Compute_Text_Extent_With_Enc()

void Compute_Text_Extent_With_Enc ( const char *  segment,
const char *  encoding,
const char *  text,
float *  xfrac,
float *  yfrac 
)

Similar to Compute_Text_Extent() but operates on encoded text rather than Latin1 text.

Parameters
segment- The segment whose attributes (or net attributes) will be applied to the problem.
encoding- The encoding method used for text.
text- The text string whose extent is to be tested.
xfrac- The fraction from 0.0 to 1.0 (or more), in the X direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.
yfrac- The fraction from 0.0 to 1.0 (or more), in the Y direction, of segment's window that is necessary to hold text. Returned to user. Passed by reference always.

DETAILS

No additional details. See Compute_Text_Extent()