GIFBUILDER is a object, which is used in many situations for creating gif-files. Anywhere the ->GIFBUILDER object is mentioned, this is the properties that apply.
When ever the "+calc"-function is added to a value in the data type of the properties underneath, you can use the dimensions of TEXT and IMAGE-objects from the GifBuilderObj-array. This is done by inserting a tag like this: "[10.w]" or "[10.h]", where "10" is the GifBuilderObj-number in the array and "w"/"h" signifies either width or height of the object.
See this example (cut from "styles.content (default)"):
styles.header.gfx1 = IMAGE
styles.header.gfx1 { wrap = {$styles.header.gfx1.wrap}file = GIFBUILDER
file { XY = [10.w]+10 ,{$styles.header.gfx1.itemH} backColor = {$styles.header.gfx1.bgCol} reduceColors = {$styles.header.gfx1.reduceColors}10 = TEXT
10 {text.current = 1
text.crop = {$styles.header.gfx1.maxChars} fontSize = {$styles.header.gfx1.fontSize} fontFile = {$styles.header.gfx1.file.fontFile} fontColor = {$styles.header.gfx1.fontColor} offset = {$styles.header.gfx1.fontOffset}}
}
}
As you see, the gif-image has a width defined as the width of the text printed onto it + 10 pixels. The height is fixed by the value of the constant {$styles.header.gfx1.itemH}
You can configure some global settings for GIFBUILDER by a top level object named “_GIFBUILDER”. One of the available properties of the global GIFBUILDER configuration is “charRangeMap”.
.charRangeMap
By this property you can globally configure mapping of font files for certain character ranges. For instance you might need GIFBUILDER to produce gif files with a certain font for latin characters while you need to use another true type font for Japanese glyphs. So what you need is to specify the usage of another font file when characters fall into another range of Unicode values.
In the GIFBUILDER object this is possible with the “splitRendering” option but if you have hundreds of GIFBUILDER objects around your site it is not very efficient to add 5-10 lines of configuration for each time you render text. Therefore this global setting allows you to match the basename of the main font face with an alternative font.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
[array] | string | Basename of font file to match for this configuration. Notice that only the filename of the font file is used - the path is stripped off. This is done to make matching easier and avoid problems when font files might move to other locations in extensions etc. So if you use the font file “EXT:myext/fonts/arial.ttf” or “t3lib/fonts/arial.ttf” both of them will match with this configuration. The key: The value of the array key will be the key used when forcing the configuration into “splitRendering” configuration of the individual GIFBUILDER objects. In the example below the key is “123”. Notice; If the key is already found in the local GIFBUILDER configuration the content of that key is respected and not overridden. Thus you can make local configurations which override the global setting. Example: _GIFBUILDER.charRangeMap {123 = arial.ttf .... | |
[array].charMapConfig | TEXT / splitRendering.[array] configuration | splitRendering configuration to set. See GIFBUILDER TEXT object for details. Example: _GIFBUILDER.charRangeMap {123 = arial.ttf 123 { charMapConfig {fontFile = t3lib/fonts/vera.ttf value = -65 fontSize = 45 } fontSizeMultiplicator = 2.3 } } This example configuration shows that GIFBUILDER TEXT objects with font faces matching “arial.ttf” will have a splitConfiguration that uses “t3lib/fonts/vera.ttf” for all characters that fall below/equal to 65 in Unicode value. | |
[array].fontSizeMultiplicator | double | If set, this will take the font size of the TEXT GIFBUILDER object and multiply with this amount (xx.xx) and override the “fontSize” property inside “charMapConfig”. | |
[array].pixelSpaceFontSizeRef | double | If set, this will multiply the four [x/y]Space[Before/After] properties of split rendering with the relationship between the fontsize and this value. In other words; Since pixel space may vary depending on the font size used you can simply specify by this value at what fontsize the pixel space settings are optimized and for other fontsizes this will automatically be adjusted according to this font size. Example: _GIFBUILDER.charRangeMap {123 = arial.ttf 123 { charMapConfig {fontFile = t3lib/fonts/vera.ttf value = 48-57 color = green xSpaceBefore = 3 xSpaceAfter = 3 } pixelSpaceFontSizeRef = 24 } } In this example xSpaceBefore and xSpaceAfter will be “3” when the font size is 24. If this configuration is used on a GIFBUILDER TEXT object where the font size is only 16 the spacing values will be corrected by “16/24”, effectively reducing the pixelspace to “2” in that case. |
[tsref:_GIFBUILDER.charRangeMap]
Whenever you see a reference to anything named an "object" in this section it's a reference to a "GifBuilderObj" and not the "cObjects" from the previous section. Confusion could happen, because both "IMAGE" and "TEXT" is a object in both areas.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
1,2,3,4... | GifBuilderObj + .if (->if) | .if (->if) is a property of all gifbuilder-objects. If the property is present and NOT set, the object is NOT rendered! This corresponds to the functionallity of ".if" of the stdWrap-function. | |
XY | x,y +calc | Size of the gif-file. | 100,20 |
format | "gif" / "jpg" | Output type. "jpg"/"jpeg" = jpg-image | gif |
reduceColors | posint (1-255) | Reduce the number of colors (if gif-file) | |
transparentBackground | boolean | Set this flag to render the background transparent. TYPO3 makes the color found at position 0,0 of the image (upper left corner) transparent. If you render text you should leave the niceText option OFF as the result with probably be more precise without the niceText antialiasing hack | |
transparentColor | HTMLColor /stdWrap | Specify a color that should be transparent Example-values: #ffffcc red 255,255,127 Option: transparentColor.closest = 1 This will allow for the closest color to be matched instead. You may need this if you image is not garanteed "clean". NOTE: You may experience that this doesn't work if you use reduceColors-option or render text with niceText-option. | |
quality | posint (10-100) | JPG-quality (if “.format” = jpg/jpeg) | |
backColor | GraphicColor /stdWrap | Background color for the gif | white |
offset | x,y +calc | Offset all objects on the gif. | 0,0 |
workArea | x,y,w,h + calc | Define the workarea on the giffile. All the GifBuilderObj's will see this as the dimensions of the gif-file regarding alignment, overlaying of images an so on. Only will TEXT-objects exceeding the boundaries of the workarea print outside this area. | |
maxWidth | pixels | Maximal width of gif-file | |
maxHeight | pixels | Maximal heigth of gif-file |
[tsref:->GIFBUILDER]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
text | stdWrap | This is text text-string on the gif-file. The item is rendered only if this string is not empty. The cObj->data-array is loaded with the page-record, if for example the GIFBUILDER-object is used by GMENU or IMGMENU | |
textMaxLength | int | The maximum length of the text. This is just a natural break that prevents incidental rendering of very long texts! | 100 |
maxWidth | pixels | Sets the maximum width in pixels, the text must be. Reduces the fontSize if the text does not fit within this width. Does not support setting alternative fontSizes in splitRendering options. (By Rene Fritz <r.fritz@colorcube.de>) | |
doNotStripHTML | boolean | If set, HTML-tags in the string inserted are NOT removed. Any other way HTML-code is removed by default! | 0 |
fontSize | posint | Font size | 12 |
fontColor | GraphicColor /stdWrap | Font color | black |
fontFile | resource | Font face (truetype font you can upload!!) | Nimbus (Arial-clone) |
angle | degree | Rotation degrees of the text. NOTE: Angle is not available if spacing/wordSpacing is set. | 0 Range: -90 til 90 |
align | align | Alignment of the text | left |
offset | x,y +calc | Offset of the text | 0,0 |
antiAlias | Boolean | FreeType antialiasing. Notice, the default mode is "on"! Note: This option is not available if .niceText is enabled | 1 |
iterations | posint | How many times the text should be "printed" onto it self. This will add the effect of bold text. Note: This option is not available if .niceText is enabled | 1 |
spacing | posint | Pixel-distance between letters. This may render ugly! | 0 |
wordSpacing | posint | Pixel-distance between words. | = ".spacing"*2 |
hide | boolean | If this is true, the text is NOT printed. 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 print. | 0 |
hideButCreateMap | boolean | 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. | |
emboss | GifBuilderObj->EMBOSS | ||
shadow | GifBuilderObj->SHADOW | ||
outline | GifBuilderObj->OUTLINE | ||
imgMap | ->IMGMAP ->stdWrap properties for "altText" and "titleText" in this case | ||
niceText | boolean | 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 giffile in twice or more times the size of the actual gif-file and then print the text onto this is a scaled dimension. Afterwards ImageMagick (IM) scales down the mask and masks the font color down on the original gif-file through the temporary mask. The fact that the font is actually rendered in the double size and scaled down adds a more homogenous shape to the lettes. Some fonts are more critical than others though. If you do not need the quality, then don't use the function. Some properties: .before = IM-params before scale .after = IM-params after scale .sharpen = sharpen-value for the mask (after scaling), integer 0-99 (this enables you to make the text crisper if it's too blurred!) .scaleFactor = scaling-factor, int 2-5 | |
splitRendering.compX splitRendering.compY splitRendering.[array] | 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 eg. Japanese and there is a separate font file for each. You can also render keywords in another font/size/color. Properties: splitRendering.compX = Additional pixelspace between parts, x direction splitRendering.compY = Additional pixelspace between parts, y direction splitRendering.[array] = keyword [charRange, highlightWord] splitRendering.[array] { fontFile = Alternative font file for this rendering fontSize = Alternative font size for this rendering color = Alternative color for this rendering, works ONLY without “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 } Keyword: charRange splitRendering.[array].value = Commaseparated list of character ranges (eg. “100-200”) given as Unicode character numbers. The list accepts optional starting and ending points, eg. “ - 200” or “ 200 -” and single values, eg. “65, 66, 67” Keyword: highlightWord splitRendering.[array].value = Word to highlight, makes a case sensitive search for this. Limitations:
Example: 10.splitRendering.compX = 2 10.splitRendering.compY = -2 10.splitRendering.10 = charRange 10.splitRendering.10 {value = 200-380 , 65, 66 fontSize = 50 fontFile = t3lib/fonts/nimbus.ttf xSpaceBefore = 30 } 10.splitRendering.20 = highlightWord 10.splitRendering.20 {value = TheWord color = red } |
[tsref:->GIFBUILDER.(GBObj).TEXT]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
offset | x,y | Shadow offset | |
color | GraphicColor | Shadow color | |
blur | posint (1-99) | Blurring of the shadow. Above 40 only values of 40,50,60,70,80,90 means something. NOTE: Unfortunately the blurring capabilities of ImageMagick is not very mature in the version 4.2.9. This is addressed in the later version 5.2.0 where a gaussian blur-function is added. BUT as we do cannot use the latest ImageMagick development yet, this is not utilized so far. | |
opacity | posint (1-100) | Opacity (transparency^-1) 100% opacity = 0% transparency). Only active with a value for blur. | |
intensity | posint(0-100) | How "massive" the shadow is. This value can - if it has a high value combined with a blurred shadow - create a kind of soft-edged outline. |
[tsref:->GIFBUILDER.(GBObj).SHADOW]
Emboss is actually two shadows offset in opposite directions and with different colors as to create an effect of light casted onto an embossed text.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
offset | x,y | Offset of the emboss | |
highColor | GraphicColor | Upper border-color | |
lowColor | GraphicColor | lower border-color | |
blur | posint (1-99) | Blurring of the shadow. Above 40 only values of 40,50,60,70,80,90 means something. | |
opacity | posint (1-100) | Opacity (transparency^-1) 100% opacity = 0% transparency). Only active with a value for blur. | |
intensity | posint(0-100) | How "massive" the emboss is. This value can - if it has a high value combined with a blurred shadow - create a kind of soft-edged outline. |
[tsref:->GIFBUILDER.(GBObj).EMBOSS]
This outline normally renderes quite ugly as it's done by print 4 or 8 texts underneath the text in question. Try to use a shadow with a high intensity. That works better!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
thickness | x,y | Thickness in each direction, range 1-2 | |
color | GraphicColor | Outline color |
[tsref:->GIFBUILDER.(GBObj).OUTLINE]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
dimensions | x,y,w,h +calc | Dimensions of a filled box. x,y is the offset. w,h is the dimensions. Dimensions of 1 will result in 1-pixel wide lines! | |
color | GraphicColor | fill-color | black |
align | VHalign |
[tsref:->GIFBUILDER.(GBObj).BOX]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
file | imgResource | The imagefile | |
offset | x,y +calc | Offset | 0,0 |
tile | x,y | tile x,y times. Maximum times is 20 each direction. If you need more, use a larger image. | |
align | VHalign | ||
mask | imgResource | Optional mask-image for the imagefile. |
[tsref:->GIFBUILDER.(GBObj).IMAGE]
.value = [Varnavn] = [value] | [Varnavn] = [value]
20 = EFFECT
20.value = gamme=1.3 | flip | rotate=180
Property: | Data type: | Description: | Default: |
|---|---|---|---|
gamma | 0.5 - 3.0 | ||
blur | 1-99 | ||
sharpen | 1-99 | ||
solarize | 0-99 | ||
swirl | 0-100 | ||
wave | ampli , length | ||
charcoal | 0-100 | ||
gray | - | ||
edge | 0-99 | ||
emboss | - | ||
flip | - | Vertical flipping | |
flop | - | Horizontal flipping | |
rotate | 0-360 | Rotation | |
colors | 2-255 | ||
shear | -90 - 90 | Horizontal shearing | |
invert | - | invert the colors |
[tsref:->GIFBUILDER.(GBObj).EFFECT]
Sets another workarea
Property: | Data type: | Description: | Default: |
|---|---|---|---|
set | x,y,w,h + calc | ||
clear | (isset) |
[tsref:->GIFBUILDER.(GBObj).WORKAREA]
NOTE: This object resets workArea to the new dimensiosn of the image!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
backColor | GraphicColor | The original backColor | |
align | VHalign | ||
crop | x,y,v,h + calc | x,y is offset of the crop-frame, v,h is the dimensions |
[tsref:->GIFBUILDER.(GBObj).CROP]
NOTE: This object resets workArea to the new dimensiosn of the image!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
width | pixels + calc | ||
height | pixels + calc | ||
params | ImageMagickParams |
[tsref:->GIFBUILDER.(GBObj).SCALE]
This lets you adjust the input-levels like in Photoshops "levels"-dialog. If you need to adjust gamma, look at the EFFECT-object.
This is used by the GifBuilderObj "TEXT" to create a image-map for the gif-file. This is especially used with the IMGMENU menuobject.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
url | url | url to link | For IMGMENU menu objects provided automatically |
target | target | target for link | For IMGMENU menu objects provided automatically |
noBlur | Boolean | Normally graphical links are "blurred" if the browser is MSIE. This removes the ugly box around a link. If this property is set, the link is NOT blurred with "onFocus". | For IMGMENU menu objects provided automatically |
explode | x,y | This "explodes" or "implodes" the image-map. Useful to let the hot area cover a little more than just the letters of the text. | |
altText | atring | Value of the alt-attribute. (Used from TEXT Gifbuilding objects, this has stdWrap properties. Otherwise not) | |
titleText | string | Value of the title attribute. (Used from TEXT Gifbuilding objects, this has stdWrap properties. Otherwise not) |
[tsref:->IMGMAP]
