.. contents:: Table of Contents .. _font: Table font ========== A table :ref:`font ` represent a true type font and can be loaded dynamically or loaded from a binary type generated by the engine. font methods ------------ font new from true type ^^^^^^^^^^^^^^^^^^^^^^^ .. data:: new(string file_name, number height, number spaceX, number spaceY, boolean save_image_as_png) :noindex: Create a new instance of a :ref:`font ` passing the file name (extension expected ``.ttf``) and the configuration expected. :param string: **file name** from true type font ``.ttf``. :param number: **height** from font in units. :param number: **spaceX** between the axis x. :param number: **spaceY** is the ``\n`` (new line space). :param boolean: **save_png** is a flag that instruct to save the font's image as png. :return: :ref:`font ` *table*. *Example:* .. code-block:: lua tArial15 = font:new('Arial.ttf',15,0,2,true) --parse runtime a new font tArial13 = font:new('Arial.ttf',13,0,2,false) --parse runtime other font .. Note:: | The :guilabel:`new` method will search in all known path. and load the file. | You can add a path to search by the method :ref:`addPath `. font new from a binary file ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. data:: new(string file_name) :noindex: Create a new instance of a :ref:`font ` passing the binary file name (extension expected ``fnt``). :param string: **file name** binary. Extension expected ``fnt``. *Example:* .. code-block:: lua tArial15 = font:new('Arial15.fnt') -- load a file previously created by the engine. tArial13 = font:new('Arial13.fnt') -- load a file previously created by the engine. .. Note:: | The :guilabel:`fnt` is an extension generated by the engine and is a binary file. | The :guilabel:`new` method will search in all known path. and load the file. | You can add a path to search by the method :ref:`addPath `. font setSpace ^^^^^^^^^^^^^ .. data:: setSpace(string axis, number value) Change the current space in the axis ``x`` or ``y``. :param string: **axis** ``x`` or ``y``. :param number: **value** from space to be applied. *Example:* .. code-block:: lua tArial15 = font:new('Arial.ttf',15,0,2) --parse runtime a new font tArial15:setSpace('x',18) tArial15:setSpace('y',0) font getSpace ^^^^^^^^^^^^^ .. data:: getSpace(string axis) Retrieve the current space from :ref:`font `. :param string: **axis** ``x`` or ``y``. :return: :literal:`number` - *space*. *Example:* .. code-block:: lua tArial15 = font:new('Arial.ttf',15,0,2) --parse runtime a new font local x = tArial15:getSpace('x') -- 0 local y = tArial15:getSpace('y') -- 2 font getHeight ^^^^^^^^^^^^^^ .. data:: getHeight() Retrieve the current height from :ref:`font `. :return: :literal:`number` - *height*. *Example:* .. code-block:: lua tArial15 = font:new('Arial.ttf',15,0,2) --parse runtime a new font local height = tArial15:getHeight() -- 15 .. _addText1: font add ^^^^^^^^ .. data:: add(string text, string * world, number * x, number * y, number * z) :noindex: Create a new instance of a :ref:`text ` from a :ref:`font `. Same as :ref:`addText `. :param string: **text** to be drew. :param string: **world** can be ``2ds``, ``2dw`` or ``3d`` (:ref:`detail `). :param number: **x** position (optional). :param number: **y** position (optional). :param number: **z** position (optional). *Example:* .. code-block:: lua tArial15 = font:new('Arial.ttf',15,0,2) --parse runtime a new font tText = tArial15:add('Hello text!','2ds',100,100) .. Note:: It might occurs error related to the character encoding. This can be solved changing the text to :guilabel:`UTF8 Without BOM` .. _addText: font addText ^^^^^^^^^^^^ .. data:: addText(string text, string * world, number * x, number * y, number * z) Create a new instance of a :ref:`text ` from a :ref:`font `. Same as :ref:`add `. :param string: **text** to be drew. :param string: **world** can be ``2ds``, ``2dw`` or ``3d`` (:ref:`detail `). :param number: **x** position (optional). :param number: **y** position (optional). :param number: **z** position (optional). *Example:* .. code-block:: lua tArial15 = font:new('Arial15.fnt') --load from binary previously generated tText = tArial15:addText('Hello text!','2dw',200,200) .. Note:: It might occurs error related to the character encoding. This can be solved changing the text to :guilabel:`UTF8 Without BOM` font methods with editor features --------------------------------- The following methods are available on desktop platforms (Linux, Windows, macOS). .. note:: These features are not available on Android builds. Size of letter ^^^^^^^^^^^^^^ .. data:: getSizeLetter(string letter) Get the size of specific letter **DO NOT** considering the rotation neither scale. :param string: **letter** to be retrieved the size :return: ``number`` *width*, ``number`` *height* - *dimension* of letter. *Example:* .. code-block:: lua local height = 20 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-20.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) local width, height = tMyFont:getSizeLetter('A') print(width,height) -- for this example width:12, height:13 .. data:: setSizeLetter(string letter,number width, number height) Force a new size of letter indicating the width and height. :param string: **letter** to be retrieved the size :param number: **width** of letter. :param number: **height** of letter. *Example:* .. code-block:: lua local height = 60 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-60.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) local width, height = tMyFont:getSizeLetter('a') print(width,height) -- for this example width:12, height:13 tMyFont:setSizeLetter(' ',10,0) --10 it is good space for this font size (I am guessing) --set the new size of letter tMyFont:setSizeLetter('a',width * 2, height) tText = tMyFont:addText("My new size\n Note the 'a'\nsomething stranger",'2dw') .. figure:: _static/font_changing_size_of_letter.png :align: center :figclass: align-center Change the dimension of the letter 'a' Displacement for letter in the axis x, y ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. data:: getLetterXDiff(string letter) Get the displacement for the specific letter in the axis ``X``. By default the value is 0. It can be negative. :param string: **letter** to be retrieved the size :return: ``number`` *displacement* - *X* of letter. *Example:* .. code-block:: lua local height = 60 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-60.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) tMyFont:setSizeLetter(' ',10,0) --space by default is not good, so we change it tMyFont:setLetterXDiff('e',10) local X = tMyFont:getLetterXDiff('e') print('Displacement:', X) .. data:: setLetterXDiff(string letter,number value) Force a new displacement for the specific letter in the axis ``X``. The value is added. It can be negative. :param string: **letter** to be retrieved the size :param number: **value** of displacement. *Example:* .. code-block:: lua local height = 60 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-60.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) tMyFont:setSizeLetter(' ',10,0) --space by default is not good, so we change it tMyFont:setLetterXDiff('e',10) tText = tMyFont:add('Some Text: Hello World!!!','2dw') .. figure:: _static/font_changing_X.png :align: center :figclass: align-center Displacement 10 in the axis ``X`` .. data:: getLetterYDiff(string letter) Get the displacement for the specific letter in the axis ``Y``. By default the value is 0. It can be negative. :param string: **letter** to be retrieved the size :return: ``number`` *displacement* - *Y* of letter. *Example:* .. code-block:: lua local height = 60 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-60.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) tMyFont:setSizeLetter(' ',10,0) --space by default is not good, so we change it tMyFont:setLetterYDiff('e',10) local y = tMyFont:getLetterYDiff('e') print('Displacement:', y) .. data:: setLetterYDiff(string letter,number value) Force a new displacement for the specific letter in the axis ``Y``. The value is added. It can be negative. :param string: **letter** to be retrieved the size :param number: **value** of displacement. *Example:* .. code-block:: lua local height = 60 --the font height local space_x = 2 --space between characters in points coordinates local space_y = 1 --space between new line characters in points coordinates local save_image_as_png = true --will save a local image as 'font_name-60.png' local base_name = 'Carlito-Regular' tMyFont = font:new(base_name .. '.ttf',height,space_x,space_y,save_image_as_png) tMyFont:setSizeLetter(' ',10,0) --space by default is not good, so we change it tMyFont:setLetterYDiff('e',10) tText = tMyFont:add('Some Text: Hello World!!!','2dw') .. figure:: _static/font_changing_Y.png :align: center :figclass: align-center Displacement 10 in the axis ``Y`` .. _creating_font: Creating a font programmatically -------------------------------- Here an example how to create a binary font from a true type file format. For this example it will be used the Carlito-Regular true type font. :download:`download Carlito-Regular.ttf <_static/Carlito-Regular.ttf>` *Example:* .. literalinclude:: example_modules/font_creating_example_1.lua :language: lua :download:`download font_creating_example_1.lua `. .. figure:: _static/font_creating_example_1.png :align: center :figclass: align-center font_creating_example_1.lua running .. figure:: _static/Carlito-Regular-50.png :align: center :figclass: align-center Carlito-Regular png generated :download:`download Carlito-Regular-50.png <_static/Carlito-Regular-50.png>`.