drawing_text_run.h
Overview
This file declares the capabilities of runs, such as obtaining the typographic boundary and drawing.
File to include: <native_drawing/drawing_text_run.h>
Library: libnative_drawing.so
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Related module: Drawing
Summary
Functions
Function Description
OH_Drawing_GetRunStringIndices()
OH_Drawing_Array* OH_Drawing_GetRunStringIndices(OH_Drawing_Run* run, int64_t start, int64_t length)
Description
Obtains an array of character indices of glyphs within a specified range of a run, where the indices are offsets relative to the entire paragraph.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| int64_t start | Start position in the run. If a negative number is passed, a null pointer is returned. |
| int64_t length | Length of the range in the run. If the length is 0, the array of all character indices in the run is obtained. If the length is less than 0, a null pointer is returned. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Array* | Returns the character index array of the glyph. Call OH_Drawing_DestroyRunStringIndices to release this pointer when the object is no longer needed. |
OH_Drawing_GetRunStringIndicesByIndex()
uint64_t OH_Drawing_GetRunStringIndicesByIndex(OH_Drawing_Array* stringIndices, size_t index)
Description
Obtains character indices of glyphs in a run by index.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* stringIndices | Pointer to a character index array. |
| size_t index | Index of the character index array. |
Returns
| Type | Description |
|---|---|
| uint64_t | Returns the character indices. |
OH_Drawing_DestroyRunStringIndices()
void OH_Drawing_DestroyRunStringIndices(OH_Drawing_Array* stringIndices)
Description
Releases the pointer to a character index array object.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* stringIndices | Pointer to a character index array. |
OH_Drawing_GetRunStringRange()
void OH_Drawing_GetRunStringRange(OH_Drawing_Run* run, uint64_t* location, uint64_t* length)
Description
Obtains the range of glyphs generated by a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| uint64_t* location | Start position of the range in the run, which is an offset relative to the entire paragraph. |
| uint64_t* length | Length of the range. |
OH_Drawing_GetRunTypographicBounds()
float OH_Drawing_GetRunTypographicBounds(OH_Drawing_Run* run, float* ascent, float* descent, float* leading)
Description
Obtains the typographic boundary of a run. The typographic boundary is related to the font and font size used for typography, but not the characters within the text.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| float* ascent | Distance from the top of the tallest character to the baseline in the run. |
| float* descent | Distance from the bottom of the lowest character to the baseline in the run. |
| float* leading | Vertical space between lines in the run. |
Returns
| Type | Description |
|---|---|
| float | Returns the layout width of the run. |
OH_Drawing_RunPaint()
void OH_Drawing_RunPaint(OH_Drawing_Canvas* canvas, OH_Drawing_Run* run, double x, double y)
Description
Paints the text contained in a run on the canvas.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Canvas* canvas | Pointer to an OH_Drawing_Canvas object. |
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| double x | X coordinate of the run. |
| double y | Y coordinate of the run. |
OH_Drawing_GetRunImageBounds()
OH_Drawing_Rect* OH_Drawing_GetRunImageBounds(OH_Drawing_Run* run)
Description
Obtains the image boundary of a run. The image boundary is related to characters and is equivalent to the visual boundary.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Rect* | Returns the pointer to an OH_Drawing_Rect object. Call OH_Drawing_DestroyRunImageBounds to release this pointer when the object is no longer needed. |
OH_Drawing_DestroyRunImageBounds()
void OH_Drawing_DestroyRunImageBounds(OH_Drawing_Rect* rect)
Description
Releases the pointer to an image boundary object of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Rect* rect | Pointer to the image boundary, which is an OH_Drawing_Rect object. |
OH_Drawing_GetRunGlyphs()
OH_Drawing_Array* OH_Drawing_GetRunGlyphs(OH_Drawing_Run* run, int64_t start, int64_t length)
Description
Obtains an array of glyphs within the specified range of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| int64_t start | Start position in the run. If a negative number is passed, a null pointer is returned. |
| int64_t length | Length of the range in the run. If the length is 0, all character indices of the run are obtained. If the length is less than 0, a null pointer is returned. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Array* | Returns the pointer to an OH_Drawing_Array object of a glyph array in a run. Call OH_Drawing_DestroyRunGlyphs to release this pointer when the object is no longer needed. |
OH_Drawing_GetRunGlyphsByIndex()
uint16_t OH_Drawing_GetRunGlyphsByIndex(OH_Drawing_Array* glyphs, size_t index)
Description
Obtains individual glyphs in a run by index.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* glyphs | Pointer to the glyph array, which is an OH_Drawing_Array object. |
| size_t index | Index of the glyph array. |
Returns
| Type | Description |
|---|---|
| uint16_t | Returns the individual glyphs. |
OH_Drawing_DestroyRunGlyphs()
void OH_Drawing_DestroyRunGlyphs(OH_Drawing_Array* glyphs)
Description
Releases the pointer to a glyph array in a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* glyphs | Pointer to the glyph array, which is an OH_Drawing_Array object. |
OH_Drawing_GetRunPositions()
OH_Drawing_Array* OH_Drawing_GetRunPositions(OH_Drawing_Run* run, int64_t start, int64_t length)
Description
Obtains the positions of glyphs within the specified range of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| int64_t start | Start position in the run. If a negative number is passed, a null pointer is returned. |
| int64_t length | Length of the range in the run. If the length is 0, all character indices of the run are obtained. If the length is less than 0, a null pointer is returned. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Array* | Returns the pointer to an OH_Drawing_Array object of a glyph position array in a run. Call OH_Drawing_DestroyRunPositions to release this pointer when the object is no longer needed. |
OH_Drawing_GetRunPositionsByIndex()
OH_Drawing_Point* OH_Drawing_GetRunPositionsByIndex(OH_Drawing_Array* positions, size_t index)
Description
Obtains the positions of individual glyphs in a run by index.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* positions | Pointer to the glyph position array, which is an OH_Drawing_Array object. |
| size_t index | Index of the glyph position array in the run. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Point* | Returns the pointer to an OH_Drawing_Point object, which holds the positions of individual glyphs in the run. |
OH_Drawing_DestroyRunPositions()
void OH_Drawing_DestroyRunPositions(OH_Drawing_Array* positions)
Description
Releases the pointer to a glyph position array in a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* positions | Pointer to the glyph position array, which is an OH_Drawing_Array object. |
OH_Drawing_GetRunGlyphCount()
uint32_t OH_Drawing_GetRunGlyphCount(OH_Drawing_Run* run)
Description
Obtains the number of glyphs in a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 18
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
Returns
| Type | Description |
|---|---|
| uint32_t | Returns the number of glyphs. |
OH_Drawing_GetRunFont()
OH_Drawing_Font* OH_Drawing_GetRunFont(OH_Drawing_Run* run)
Description
Obtains the font object of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Font* | Returns the pointer to an OH_Drawing_Font object in a run. Call OH_Drawing_FontDestroy to release this pointer when the object is no longer needed. |
OH_Drawing_GetRunTextDirection()
OH_Drawing_TextDirection OH_Drawing_GetRunTextDirection(OH_Drawing_Run* run)
Description
Obtains the text direction of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_TextDirection | Returns the text direction of a run. 0: TEXT_DIRECTION_RTL, which means right-to-left; 1: TEXT_DIRECTION_LTR, which means left-to-right. For details, see OH_Drawing_TextDirection. |
OH_Drawing_GetRunGlyphAdvances()
OH_Drawing_Array* OH_Drawing_GetRunGlyphAdvances(OH_Drawing_Run* run, uint32_t start, uint32_t length)
Description
Obtains the glyph advance array of a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Run* run | Pointer to an OH_Drawing_Run object. |
| uint32_t start | Start position in the run. If a negative number is passed, a null pointer is returned. |
| uint32_t length | Length of the range in the run. If the length is 0, all glyph advances from the start to the end of the run are obtained. If the length is less than 0, a null pointer is returned. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Array* | Returns the pointer to an OH_Drawing_Array object of a glyph advance array in a run. Call OH_Drawing_DestroyRunGlyphAdvances to release this pointer when the object is no longer needed. |
OH_Drawing_GetRunGlyphAdvanceByIndex()
OH_Drawing_Point* OH_Drawing_GetRunGlyphAdvanceByIndex(OH_Drawing_Array* advances, size_t index)
Description
Obtains the advances of individual glyphs in a run by index.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* advances | Pointer to the glyph advance array, which is an OH_Drawing_Array object. |
| size_t index | Index of the glyph advance array in a run. |
Returns
| Type | Description |
|---|---|
| OH_Drawing_Point* | Returns the pointer to an OH_Drawing_Point object, which holds the advance of individual glyphs in the run. x indicates the advance, and y is a reserved field and defaults to 0. |
OH_Drawing_DestroyRunGlyphAdvances()
void OH_Drawing_DestroyRunGlyphAdvances(OH_Drawing_Array* advances)
Description
Releases the pointer to a glyph advance array in a run.
System capability: SystemCapability.Graphic.Graphic2D.NativeDrawing
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Drawing_Array* advances | Pointer to the glyph advance array, which is an OH_Drawing_Array object. |