| CRM64Pro GDK v0.18.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
CRM64Pro::Fontfinal
Graphics modules » Font

Font Object class. More...

## Detailed Description

Font Object class.

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request Font object information.
const string & | getName () const override
| Get the name.
Sint32 | getID () const override
| Get the ID.
Sint32 | assignImage (Sint32 idImage, Sint32 iOwnership=0)
| Assign an Image to this font.
Sint32 | getImage () const
| Get the assigned Image of this font.
bool | setTextCursor (Uint8 cCursor)
| Set the text input cursor character.
Uint8 | getTextCursor () const
| Get the text input cursor character.
Sint32 | getCursorPositionByPixel (const string &sText, Sint32 iPixelPos) const
| Get the cursor position given a number of pixels.
bool | setKerning (Sint32 iKer)
| Set the kerning value.
Sint32 | getKerning () const
| Get the kerning value.
bool | setSpaceWidth (Sint32 iWidth)
| Set the space character width.
Sint32 | getSpaceWidth () const
| Get the space character width.
Sint32 | getWidth (const string &sText, Sint32 iCurPos=-1) const
| Get the width of the given string (in pixels).
Sint32 | getHeight () const
| Get the height of this font (in pixels).
bool | setPosition (const Position &rPosX, const Position &rPosY)
| Set the font position.
const Position & | getPositionX () const
| Get the font X position.
const Position & | getPositionY () const
| Get the font Y position.
Sint32 | render (const string &sText, bool bShowCursor=false, Sint32 iCurPos=-1, Sint32 idRes=0)
| Render a text using this font.
Sint32 | renderEx (const string &sText, bool bShowCursor=false, Sint32 iCurPos=-1, float fScaleX=1.0f, float fScaleY=1.0f, double dAngle=0.0, const SDL_FPoint *pCenter=nullptr, SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0)
| Render a text using this font.
Sint32 | save (const string &sCDCFile, const string &sResourceName="")
| Save the font to a CDC file.
Sint32 | save (Sint32 idCDC, const string &sResourceName="")
| Save the font to a CDC file.

## Member Function Documentation

## ◆ info()

bool CRM64Pro::Font::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Font object information.

Writes information to the default log.

Parameters

  iMode | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::Font::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Sint32 CRM64Pro::Font::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ assignImage()

Sint32 CRM64Pro::Font::assignImage | ( | Sint32 | idImage,
|  | Sint32 | iOwnership = 0 )

Assign an Image to this font.

It is mainly used for associating an Image to the font when it is created via FontMgr::create().

Parameters

  idImage | Image id with the whole characters set. They are identified using alpha channel so the image needs to have colorkey/alpha channel enabled.
  iOwnership | 0 for creating our own copy of the image or any other value for taking the ownership of the image; in this case, the image cannot be already owned by another item. By default it is set to 0.

Returns
  0 on success, or a negative error code on failure.

Note
  When re-assigning a new image, the old one will be closed.

## ◆ getImage()

Sint32 CRM64Pro::Font::getImage | ( |  | ) | const

Get the assigned Image of this font.

Returns
  Greater than 0 on success (the Image id), or a negative error code on failure.

## ◆ setTextCursor()

bool CRM64Pro::Font::setTextCursor | ( | Uint8 | cCursor | ) |

Set the text input cursor character.

Sets the character used to render a text input cursor. This is not the mouse cursor managed by CursorMgr.

Parameters

  cCursor | Printable ASCII character from '!' to '~'.

Returns
  true on success, or false on failure.

## ◆ getTextCursor()

Uint8 CRM64Pro::Font::getTextCursor | ( |  | ) | const

Get the text input cursor character.

Returns
  Printable ASCII character from '!' to '~'. This is not the mouse cursor managed by CursorMgr.

## ◆ getCursorPositionByPixel()

Sint32 CRM64Pro::Font::getCursorPositionByPixel | ( | const string & | sText,
|  | Sint32 | iPixelPos ) const

Get the cursor position given a number of pixels.

Parameters

  sText | String to get the cursor position.
  iPixelPos | Pixel position to convert to cursor position.

Returns
  Cursor byte position in the supported ASCII text range on success, or a negative error code on failure.

Note
  Cursor positions in the Font module are byte-based and assume the built-in ASCII bitmap character set.
  If the pixel position is outside the text width, a negative error code is returned.

## ◆ setKerning()

bool CRM64Pro::Font::setKerning | ( | Sint32 | iKer | ) |

Set the kerning value.

Parameters

  iKer | Signed integer added to the fixed character gap in pixels.

Returns
  true on success, or false on failure.

## ◆ getKerning()

Sint32 CRM64Pro::Font::getKerning | ( |  | ) | const

Get the kerning value.

Returns
  Signed integer added to the fixed character gap in pixels.

## ◆ setSpaceWidth()

bool CRM64Pro::Font::setSpaceWidth | ( | Sint32 | iWidth | ) |

Set the space character width.

Parameters

  iWidth | Space width in pixels. Use 0 to keep the automatic width derived from the assigned image.

Returns
  true on success, or false on failure.

## ◆ getSpaceWidth()

Sint32 CRM64Pro::Font::getSpaceWidth | ( |  | ) | const

Get the space character width.

Returns
  Effective space width in pixels.

## ◆ getWidth()

Sint32 CRM64Pro::Font::getWidth | ( | const string & | sText,
|  | Sint32 | iCurPos = -1 ) const

Get the width of the given string (in pixels).

Parameters

  sText | String to get its width.
  iCurPos | Up to this byte position. By default, it is set to -1 for positioning the cursor at the end of the string.

Note
  Width calculation only supports the printable ASCII character set available in the assigned bitmap font.

Returns
  String width in pixels, 0 for an empty string, or a negative error code on failure.

## ◆ getHeight()

Sint32 CRM64Pro::Font::getHeight | ( |  | ) | const

Get the height of this font (in pixels).

Returns
  Font height in pixels, or a negative error code on failure.

## ◆ setPosition()

bool CRM64Pro::Font::setPosition | ( | const Position & | rPosX,
|  | const Position & | rPosY )

Set the font position.

Parameters

  rPosX | Position struct with X position. Can be absolute (float) or use position helpers from ::ePositionHelper enum.
  rPosY | Position struct with Y position. Can be absolute (float) or use position helpers from ::ePositionHelper enum.

Returns
  true on success, or false on failure.

Note
  Supports implicit conversion from float: setPosition(100.0f, 200.0f) or explicit helpers: setPosition(Position(PH_CENTER, -10.0f), Position(PH_TOP))

## ◆ getPositionX()

const Position & CRM64Pro::Font::getPositionX | ( |  | ) | const

Get the font X position.

Returns
  The Position struct containing X position (absolute or with helper).

## ◆ getPositionY()

const Position & CRM64Pro::Font::getPositionY | ( |  | ) | const

Get the font Y position.

Returns
  The Position struct containing Y position (absolute or with helper).

## ◆ render()

Sint32 CRM64Pro::Font::render | ( | const string & | sText,
|  | bool | bShowCursor = false,
|  | Sint32 | iCurPos = -1,
|  | Sint32 | idRes = 0 )

Render a text using this font.

Parameters

  sText | String with the text to be rendered.
  bShowCursor | true to show the text input cursor, false to hide it.
  iCurPos | Byte position of the cursor on the given text. By default it is set to -1 which means at the end.
  idRes | A valid screen or image handle. By default it tries to use the default screen.

Note
  Rendering is limited to the printable ASCII character set available in the assigned bitmap font.

Returns
  0 on success, or a negative error code on failure.

## ◆ renderEx()

Sint32 CRM64Pro::Font::renderEx | ( | const string & | sText,
|  | bool | bShowCursor = false,
|  | Sint32 | iCurPos = -1,
|  | float | fScaleX = 1.0f,
|  | float | fScaleY = 1.0f,
|  | double | dAngle = 0.0,
|  | const SDL_FPoint * | pCenter = nullptr,
|  | SDL_FlipMode | rf = SDL_FLIP_NONE,
|  | Sint32 | idRes = 0 )

Render a text using this font.

Parameters

  sText | String with the text to be rendered.
  bShowCursor | true to show the text input cursor, false to hide it.
  iCurPos | Byte position of the cursor on the given text. By default it is set to -1 which means at the end.
  fScaleX | X scaling factor.
  fScaleY | Y scaling factor.
  dAngle | An angle in degrees that indicates the rotation that will be applied.
  pCenter | SDL_FPoint pointer indicating the point around which each character will be rotated. By default, it is set to nullptr and the rotation will be done around pDst->w/2 and pDst->h/2.
  rf | SDL_FlipMode value stating which flipping actions should be performed.
  idRes | A valid screen or image handle. By default it tries to use the default screen.

Note
  Rendering is limited to the printable ASCII character set available in the assigned bitmap font.

Returns
  0 on success, or a negative error code on failure.

## ◆ save() [1/2]

Sint32 CRM64Pro::Font::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save the font to a CDC file.

The associated image will also be saved into the same CDC file.

Parameters

  sCDCFile | String containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Font object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  If the font already exists, it will be overwritten. If the font is a child, the parent font will be saved.

## ◆ save() [2/2]

Sint32 CRM64Pro::Font::save | ( | Sint32 | idCDC,
|  | const string & | sResourceName = "" )

Save the font to a CDC file.

The associated image will also be saved into the same CDC file.

Parameters

  idCDC | CDC id.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Font object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  If the font already exists, it will be overwritten. If the font is a child, it will call the save method of its parent.