From b59389b526895b5d557d30bcef1cca1d5e31f6b0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 12 Nov 2023 18:49:41 +0100 Subject: [PATCH] [Backport 12.4] [TASK] Revise GIFBUILDER object WORKAREA (#899) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace container table-row with a sphinx object type - Add a TOC for the properties - Sort properties alphabetically - Add references where appropriate - Remove hideButCreateMap property as this was removed in some TYPO3 version before v11.5 Releases: main, 12.4, 11.5 Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../Gifbuilder/ObjectNames/Text/Index.rst | 587 +++++++++--------- Documentation/Settings.cfg | 1 + 2 files changed, 305 insertions(+), 283 deletions(-) diff --git a/Documentation/Gifbuilder/ObjectNames/Text/Index.rst b/Documentation/Gifbuilder/ObjectNames/Text/Index.rst index 6c72a873..e40db777 100644 --- a/Documentation/Gifbuilder/ObjectNames/Text/Index.rst +++ b/Documentation/Gifbuilder/ObjectNames/Text/Index.rst @@ -8,478 +8,499 @@ TEXT Renders a text. + Properties ========== -.. ### BEGIN~OF~TABLE ### +.. contents:: + :local: -.. container:: table-row - Property - text +.. _gifbuilder-text-align: - Data type - string / :ref:`stdWrap ` +align +----- - Description - This is text text-string on the image file. The item is rendered only - if this string is not empty. +.. t3-gifbuilder-text:: align - The $cObj->data-array is loaded with the page-record, if for example - the GIFBUILDER object is used in TypoScript. + :Data type: align / :ref:`stdWrap ` + :Default: left + The alignment of the :ref:`text `. -.. container:: table-row + Possible values: - Property - breakWidth + * :typoscript:`left` + * :typoscript:`center` + * :typoscript:`right` - Data type - integer /:ref:`stdWrap ` - Description - Defines the maximum width for an object, overlapping elements will - force an automatic line break. +.. _gifbuilder-text-angle: +angle +----- -.. container:: table-row +.. t3-gifbuilder-text:: angle - Property - breakSpace + :Data type: :t3-data-type:`degree` + :Default: 0 + :Range: -90 to 90 - Data type - float + The rotation degree of the :ref:`text `. - Default - 1.0 + .. note:: + The angle is not available, if :ref:`spacing ` + / :ref:`wordSpacing ` is set. - Description - Defines a value that is multiplied by the line height of the current - element. +.. _gifbuilder-text-antiAlias: +antiAlias +--------- -.. container:: table-row +.. t3-gifbuilder-text:: antiAlias - Property - textMaxLength + :Data type: boolean + :Default: 1 (true) - Data type - integer + The FreeType antialiasing. - Default - 100 + .. note:: + This option is not available, if + :ref:`niceText ` is enabled. - Description - The maximum length of the text. This is just a natural break that - prevents incidental rendering of very long texts! + Setting this option to :typoscript:`0` will not work, if + :ref:`fontColor ` is set to black (or + #000000). +.. _gifbuilder-text-breakSpace: -.. container:: table-row +breakSpace +---------- - Property - maxWidth +.. t3-gifbuilder-text:: breakSpace - Data type - pixels /:ref:`stdWrap ` + :Data type: float + :Default: 1.0 - Description - Sets the maximum width in pixels, the text must be. Reduces the - fontSize if the text does not fit within this width. + Defines a value that is multiplied by the line height of the current + element. - Does not support setting alternative fontSizes in splitRendering - options. - (By René Fritz ) +.. _gifbuilder-text-breakWidth: +breakWidth +---------- -.. container:: table-row +.. t3-gifbuilder-text:: breakWidth - Property - doNotStripHTML + :Data type: integer / :ref:`stdWrap ` - Data type - boolean + Defines the maximum width for an object, overlapping elements will + force an automatic line break. - Default - 0 (false) - Description - If set, HTML-tags in the string inserted are **not** removed. Any - other way HTML code is removed by default! +.. _gifbuilder-text-doNotStripHTML: +doNotStripHTML +-------------- -.. _gifbuilder-text-fontSize: +.. t3-gifbuilder-text:: doNotStripHTML -.. container:: table-row + :Data type: boolean + :Default: 0 (false) - Property - fontSize + If set, HTML tags inserted in the :ref:`text ` are + **not** removed. Any other HTML code will be removed by default! - Data type - positive integer /:ref:`stdWrap ` - Default - 12 +.. _gifbuilder-text-emboss: - Description - Font size +emboss +------ +.. t3-gifbuilder-text:: emboss + :Data type: GIFBUILDER object :ref:`->EMBOSS ` -.. container:: table-row - Property - fontColor +.. _gifbuilder-text-fontColor: - Data type - :t3-data-type:`GraphicColor` /:ref:`stdWrap ` +fontColor +--------- - Default - black +.. t3-gifbuilder-text:: fontColor - Description - Font color + :Data type: :t3-data-type:`GraphicColor` / :ref:`stdWrap ` + :Default: black + The font color. -.. container:: table-row +.. _gifbuilder-text-fontFile: - Property - fontFile +fontFile +-------- - Data type - resource /:ref:`stdWrap ` +.. t3-gifbuilder-text:: fontFile - Default - Nimbus (Arial-clone) + :Data type: resource / :ref:`stdWrap ` + :Default: Nimbus (Arial clone) - Description - Font face (truetype \*.ttf and opentype \*.otf font you can upload!) + The font face (TrueType :file:`*.ttf` and OpenType :file:`*.otf` fonts can be + used). +.. _gifbuilder-text-fontSize: -.. container:: table-row +fontSize +-------- - Property - angle +.. t3-gifbuilder-text:: fontSize - Data type - :t3-data-type:`degree` + :Data type: positive integer / :ref:`stdWrap ` + :Default: 12 - Default - 0 + The font size. - Range: -90 til 90 - Description - Rotation degrees of the text. +.. _gifbuilder-text-hide: - **Note:** Angle is not available if spacing/wordSpacing is set. +hide +---- +.. t3-gifbuilder-text:: hide + :Data type: boolean / :ref:`stdWrap ` + :Default: 0 (false) -.. container:: table-row + If this is true, the text is **not** printed. - Property - align + This feature may be used, if you need a :ref:`SHADOW ` + object to base a shadow on the text, but do not want the text to be + displayed. - Data type - align /:ref:`stdWrap ` - Default - left +.. _gifbuilder-text-iterations: - Description - Alignment of the text +iterations +---------- +.. t3-gifbuilder-text:: iterations + :Data type: positive integer / :ref:`stdWrap ` + :Default: 1 -.. container:: table-row + How many times the :ref:`text ` should be "printed" + onto it self. This will add the effect of bold text. - Property - offset + .. note:: + This option is not available, if + :ref:`niceText ` is enabled. - Data type - x,y +calc /:ref:`stdWrap ` - Default - 0,0 +.. _gifbuilder-text-maxWidth: - Description - Offset of the text +maxWidth +-------- +.. t3-gifbuilder-text:: maxWidth + :Data type: positive integer / :ref:`stdWrap ` -.. container:: table-row + Sets the maximum width in pixels, the :ref:`text ` + must be. Reduces the :ref:`font size `, if the + text does not fit within this width. - Property - antiAlias + Does not support setting alternative font sizes in + :ref:`splitRendering ` options. - Data type - boolean - Default - 1 (true) +.. _gifbuilder-text-niceText: - Description - FreeType antialiasing. Notice, the default mode is "on"! +niceText +-------- - **Note:** This option is not available if .niceText is enabled. +.. t3-gifbuilder-text:: niceText - **Note:** setting this option to 0 will not work if *fontColor* is set to black (or #000000). + :Data type: boolean / :ref:`stdWrap ` + This is a very popular feature that helps to render small letters much nicer + than the FreeType library can normally do. But it also loads the system + very much! + The principle of this function is to create a black/white image file in + twice or more times the size of the actual image file and then print the + text onto this in a scaled dimension. Afterwards GraphicsMagick/ImageMagick + scales down the mask and masks the + :ref:`font color ` down on the original image + file through the temporary mask. + The fact that the font is actually rendered in the double size and + scaled down adds a more homogeneous shape to the letters. Some fonts + are more critical than others though. If you do not need the quality, + then do not use the function. -.. container:: table-row - Property - iterations +.. _gifbuilder-text-niceText-after: - Data type - positive integer /:ref:`stdWrap ` +after +~~~~~ - Default - 1 +.. t3-gifbuilder-text:: niceText.after - Description - How many times the text should be "printed" onto it self. This will - add the effect of bold text. + GraphicsMagick/ImageMagick parameters after scale. - **Note:** This option is not available if .niceText is enabled. +.. _gifbuilder-text-niceText-before: +before +~~~~~~ -.. container:: table-row +.. t3-gifbuilder-text:: niceText.before - Property - spacing + GraphicsMagick/ImageMagick parameters before scale. - Data type - positive integer /:ref:`stdWrap ` - Default - 0 +.. _gifbuilder-text-niceText-scaleFactor: - Description - Pixel-distance between letters. This may render ugly! +scaleFactor +~~~~~~~~~~~ +.. t3-gifbuilder-text:: niceText.scaleFactor + :Data type: integer (2-5) -.. container:: table-row + The scaling factor. - Property - wordSpacing - Data type - positive integer /:ref:`stdWrap ` +.. _gifbuilder-text-niceText-sharpen: - Default - = ".spacing"\*2 +sharpen +~~~~~~~ - Description - Pixel-distance between words. +.. t3-gifbuilder-text:: niceText.sharpen + :Data type: integer (0-99) + The sharpen value for the mask (after scaling). This enables you to make the + text crisper, if it is too blurred! -.. container:: table-row - Property - hide +.. _gifbuilder-text-offset: - Data type - boolean /:ref:`stdWrap ` +offset +------ - Default - 0 +.. t3-gifbuilder-text:: offset - Description - If this is true, the text is **not** printed. + :Data type: x,y :ref:`+calc ` / :ref:`stdWrap ` + :Default: 0,0 - This feature may be used, if you need a SHADOW object to base a shadow - on the text, but do not want the text to be displayed. + The offset of the :ref:`text `. +.. _gifbuilder-text-outline: -.. container:: table-row +outline +------- - Property - hideButCreateMap +.. t3-gifbuilder-text:: outline - Data type - boolean /:ref:`stdWrap ` + :Data type: GIFBUILDER object :ref:`->OUTLINE ` - Description - If this option is set, the text will not be rendered. Shadows and - emboss will, though, so don't apply these! But this feature is also - meant only to enable a text to generate the imageMap coordinates - without rendering itself. +.. _gifbuilder-text-shadow: -.. container:: table-row +shadow +------ - Property - emboss +.. t3-gifbuilder-text:: shadow - Data type - Gifbuilder Object->EMBOSS + :Data type: GIFBUILDER object :ref:`->SHADOW ` -.. container:: table-row +.. _gifbuilder-text-spacing: - Property - shadow +spacing +------- - Data type - Gifbuilder Object->SHADOW +.. t3-gifbuilder-text:: spacing + :Data type: positive integer / :ref:`stdWrap ` + :Default: 0 -.. container:: table-row + The pixel distance between letters. This may render ugly! - Property - outline - Data type - Gifbuilder Object->OUTLINE +.. _gifbuilder-text-splitRendering: +splitRendering +-------------- -.. _gifbuilder-text-niceText: +.. t3-gifbuilder-text:: splitRendering -.. container:: table-row + :Data type: integer / *(array of keys)* - Property - niceText + Split the rendering of a string into separate processes with individual + configurations. By this method a certain range of characters can be rendered + with another font face or size. This is very useful if you want to use + separate fonts for strings where you have latin characters combined with, + for example, Japanese and there is a separate font file for each. - Data type - boolean /:ref:`stdWrap ` + You can also render keywords in another + :ref:`font ` / + :ref:`size ` / + :ref:`color `. - Description - This is a very popular feature that helps to render small letters much - nicer than the freetype library can normally do. But it also loads the - system very much! - The principle of this function is to create a black/white image file - in twice or more times the size of the actual image file and then - print the text onto this in a scaled dimension. Afterwards - GraphicsMagick/ImageMagick scales down the mask and masks the font - color down on the original image file through the temporary mask. +.. _gifbuilder-text-splitRendering-array: - The fact that the font is actually rendered in the double size and - scaled down adds a more homogeneous shape to the letters. Some fonts - are more critical than others though. If you do not need the quality, - then don't use the function. +[array] +~~~~~~~ - **Some sub-properties:** +.. t3-gifbuilder-text:: splitRendering.[array] - .before = GraphicsMagick/ImageMagick-params before scale + :Data type: integer - .after = GraphicsMagick/ImageMagick-params after scale + With keyword being [charRange, highlightWord]. - .sharpen = sharpen-value for the mask (after scaling), integer 0-99 - (this enables you to make the text crisper if it's too blurred!) + * **splitRendering.[array] = keyword** with keyword being + [:ref:`charRange `, + :ref:`highlightWord `] - .scaleFactor = scaling-factor, integer 2-5 + * **splitRendering.[array] {** + * **fontFile:** Alternative font file for this rendering. -.. _gifbuilder-text-splitRendering: + * **fontSize:** Alternative font size for this rendering. + + * **color:** Alternative color for this rendering, works *only* + without :ref:`niceText `. + + * **xSpaceBefore:** x space before this part. + + * **xSpaceAfter:** x space after this part. + + * **ySpaceBefore:** y space before this part. + + * **ySpaceAfter:** y space after this part. + + **}** + + .. _gifbuilder-text-splitRendering-charRange: + + **Keyword: charRange** + + :typoscript:`splitRendering.[array].value` = Comma-separated list of + character ranges (for example, :typoscript:`100-200`) given as Unicode + character numbers. The list accepts optional starting and ending points, + for example, :typoscript:`- 200` or :typoscript:`200 -` and single values, + for example, :typoscript:`65, 66, 67`. + + .. _gifbuilder-text-splitRendering-highlightWord: + + **Keyword: highlightWord** + + :typoscript:`splitRendering.[array].value` = Word to highlight, makes a case + sensitive search for this. + + **Limitations:** + + * The pixel compensation values are not corrected for scale factor used + with :ref:`niceText `. Basically this means + that when :typoscript:`niceText` is used, these values will have only + the half effect. + + * When word spacing is used the :typoscript:`highlightWord` mode does not + work. -.. container:: table-row + * The color override works only without :typoscript:`niceText`. - Property - splitRendering.compX + **Example:** - splitRendering.compY + .. code-block:: typoscript + :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript - splitRendering.[array] + 10.splitRendering.compX = 2 + 10.splitRendering.compY = -2 + 10.splitRendering.10 = charRange + 10.splitRendering.10 { + value = 200-380 , 65, 66 + fontSize = 50 + fontFile = EXT:core/Resources/Private/Font/nimbus.ttf + xSpaceBefore = 30 + } + 10.splitRendering.20 = highlightWord + 10.splitRendering.20 { + value = TheWord + color = red + } - Data type - integer / *(array of keys)* - Description - Split the rendering of a string into separate processes with - individual configurations. By this method a certain range of - characters can be rendered with another font face or size. This is - very useful if you want to use separate fonts for strings where you - have latin characters combined with e.g. Japanese and there is a - separate font file for each. +.. _gifbuilder-text-splitRendering-compX: - You can also render keywords in another font/size/color. +compX +~~~~~ - **Properties:** +.. t3-gifbuilder-text:: splitRendering.compX - * **splitRendering.compX:** Integer. Additional pixelspace between - parts, x direction. + :Data type: integer - * **splitRendering.compY:** Integer. Additional pixelspace between - parts, y direction. + Additional pixel space between parts, x direction. - * **splitRendering.[array] = keyword** with keyword being [charRange, - highlightWord] - * **splitRendering.[array] {** +.. _gifbuilder-text-splitRendering-compY: - * **fontFile:** Alternative font file for this rendering. +compY +~~~~~ - * **fontSize:** Alternative font size for this rendering. +.. t3-gifbuilder-text:: splitRendering.compY - * **color:** Alternative color for this rendering, works *only* - without "niceText". + :Data type: integer - * **xSpaceBefore:** x-Space before this part. + Additional pixel space between parts, y direction. - * **xSpaceAfter:** x-Space after this part. - * **ySpaceBefore:** y-Space before this part. +.. _gifbuilder-text-text: - * **ySpaceAfter:** y-Space after this part. +text +---- +.. t3-gifbuilder-text:: text + :Data type: string / :ref:`stdWrap ` - **Keyword: charRange** + This is text on the image file. The item is rendered only, if this string is + not empty. - splitRendering.[array].value = Comma-separated list of character ranges - (e.g. "100-200") given as Unicode character numbers. The list accepts - optional starting and ending points, e.g. " - 200" or " 200 -" and - single values, e.g. "65, 66, 67". + The :php:`$cObj->data` array is loaded with the page record, if, for + example, the :typoscript:`GIFBUILDER` object is used in TypoScript. - **Keyword: highlightWord** - splitRendering.[array].value = Word to highlight, makes a case - sensitive search for this. +.. _gifbuilder-text-textMaxLength: - **Limitations:** +textMaxLength +------------- - - The pixel compensation values are not corrected for scale factor used - with niceText. Basically this means that when niceText is used, these - values will have only the half effect. +.. t3-gifbuilder-text:: textMaxLength - - When word spacing is used the "highlightWord" mode does not work. + :Data type: integer + :Default: 100 - - The color override works only without "niceText". + The maximum length of the :ref:`text `. This is just a + natural break that prevents incidental rendering of very long texts! - **Example:** - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript +.. _gifbuilder-text-wordSpacing: - 10.splitRendering.compX = 2 - 10.splitRendering.compY = -2 - 10.splitRendering.10 = charRange - 10.splitRendering.10 { - value = 200-380 , 65, 66 - fontSize = 50 - fontFile = typo3/sysext/core/Resources/Private/Font/nimbus.ttf - xSpaceBefore = 30 - } - 10.splitRendering.20 = highlightWord - 10.splitRendering.20 { - value = TheWord - color = red - } +wordSpacing +----------- +.. t3-gifbuilder-text:: wordSpacing -.. ###### END~OF~TABLE ###### + :Data type: positive integer /:ref:`stdWrap ` + :Default: :ref:`spacing ` * 2 -[tsref:->GIFBUILDER.(GBObj).TEXT] + The pixel distance between words. diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg index bde8fbd2..a1ebe55f 100644 --- a/Documentation/Settings.cfg +++ b/Documentation/Settings.cfg @@ -85,6 +85,7 @@ t3-gifbuilder-image = t3-gifbuilder-image // t3-gifbuilder-image // GIFBUILDER o t3-gifbuilder-outline = t3-gifbuilder-outline // t3-gifbuilder-outline // GIFBUILDER object OUTLINE t3-gifbuilder-scale = t3-gifbuilder-scale // t3-gifbuilder-scale // GIFBUILDER object SCALE t3-gifbuilder-shadow = t3-gifbuilder-shadow // t3-gifbuilder-shadow // GIFBUILDER object SHADOW +t3-gifbuilder-text = t3-gifbuilder-text // t3-gifbuilder-text // GIFBUILDER object TEXT t3-gifbuilder-workarea = t3-gifbuilder-workarea // t3-gifbuilder-workarea // GIFBUILDER object WORKAREA t3-menu-tmenu = t3-menu-tmenu // t3-menu-tmenu // TMENU