RMagick 2.9.0: RVG Reference: RVG::Text Class

###### RMagick 2.9.0 User's Guide and Reference

# class RVG::Text < Object

## class methods

### new

RVG::Text.new(x=0, y=0, text=nil) [ { |text| ...} ] -> text

#### Description

This method is usually invoked indirectly via the text method in the RVG::ClipPath, RVG::Group, RVG::Pattern, and RVG classes.

Text objects are containers, so this method yields to a block if one is present. A text object can contain RVG::Tspan objects that are added directly via tspan, or indirectly via tref.

#### Arguments

All arguments are optional. You can omit all the arguments when you just want to use the `text` object as a container for `tspans`.

x, y
  The [x, y] coordinate of the initial text position within the current user coordinate system. If omitted the default is [0, 0].
text
  A string. If present, this string is drawn at the initial text position. If omitted, only the initial text position is established. By default the string is positioned with the lower-left corner of the first glyph at [x, y]. Use the :text_anchor style to override this behavior. After the string is rendered, the current text position is moved to the end of the string.

#### Example

## instance methods

### d

text.d(dx[, dy=0]) [ { |self| ...} ] -> self

#### Description

The dx and dy arguments are added to the x and y `text` arguments to form the initial text position. Yields to a block if one is present.

#### Arguments

dx, dy
  The distance, in the user coordinate system, to be added to the x and y coordinates of the initial text position.

#### Returns

self

### rotate

text.rotate(degrees) [ { |text| ...} ] -> self

#### Description

Rotates the text about the initial text position by the specified number of degrees. Yields to a block if one is present.

#### Arguments

degrees
  The amount of rotation

#### Returns

self

### tref

text.tref(tspan, x=0, y=0) -> self

#### Description

Adds the referenced Tspan object to the text container.

#### Arguments

tspan
  A `Tspan` object.
x, y
  The absolute text position

#### Example

### tspan

text.tspan(string=nil, x=nil, y=nil) [ { |tspan| ...} ] -> tspan

#### Description

Calls RVG::Tspan.new to construct a tspan and adds it to the enclosing RVG::Text object. Yields to a block if one is present, passing the new tspan as an argument.

Although `tspan` has the same arguments as `RVG::Text.new` they are not in the same order. The `tspan` method has the string argument first followed by the [x, y] arguments. The `RVG::Text.new` arguments are just the opposite.

#### Arguments

string
  A text string.
x, y
  The absolute text position

#### Returns

The new tspan, so other `RVG::Tspan` methods can be chained to it.

## text styles

### basic styles

#### Description

The basic styles include font styles and text styles. Note that ImageMagick uses the font styles to select a font from the available fonts. If it cannot find a font that exactly matches it will use the closest matching font. Unlike MS Windows, ImageMagick will not alter a font - by artificially slanting it to to simulate italics, for example - to produce a match.

#### Styles

:font
  font name or font file name, such as "C:/Windows/Fonts/Arial.ttf" or "pfb:-urw-helvetica-medium-o-condensed--0-0-0-0-p-0-iso10646-1"
:font_family
  font family name, such as "serif" or "courier"
:font_size
  the font size in points
:font_stretch
  one of the following strings: 'normal', 'ultra_condensed', 'extra_condensed', 'condensed', 'semi_condensed', 'semi_expanded', 'expanded', 'extra_expanded', 'ultra_expanded'
:font_style
  one of the following strings: 'normal', 'italic', 'oblique'
:font_weight
  one of the following strings: 'normal', 'bold', 'bolder', 'lighter', or a multiple of 100 between 100 and 900
:text_anchor
  one of the following strings: 'start', 'middle', 'end'
:text_decoration
  one of the following strings: 'none', 'underline', 'overline', 'line_through'

#### Examples

font styles Depending on the fonts that ImageMagick is configured with you may not see the effect of some of the styles used in this example.

text styles

### advanced styles

#### Description

These styles are emulated by RVG by orienting and positioning each glyph individually. Consequently any use of a non-default value for one of these styles will probably cause your script to dramatically slow down. If you specify an invalid value for any of these styles RVG ignores the value and uses the default. RVG frequently uses approximate measurements to emulate these styles so the results will not be as precise as when ImageMagick is doing the work.

#### Styles

:writing_mode
  There are two possible values for :writing_mode, 'lr' for left-to-right (most Latin-based documents) and 'tb' for top-to-bottom (or vertical) text such as for column labels. The default is 'lr'.
:baseline_shift
  Adjusts the baseline. There are five possible values: 'baseline' (the default), 'super', 'sub', a percentage specified as 'NN%', or a number. For the last two choices, positive numbers move the baseline upward. The percentage is a percentage of the line height.
:letter_spacing
  Specifies an amount of space to be added between each letter. The default is 0.
:word_spacing
  Specifies an amount of space to be added between each word. This amount is added for each blank between words, so if the words are separated by two blanks, for example, then twice the additional space is added. The default is 0.
  RVG uses this statement to separate words: words = text.split(::Magick::RVG::WORD_SEP) You can change the regular expression that RVG uses to determine word breaks by assigning a new regular expression to the `::Magick::RVG::WORD_SEP` constant. By default the value of `::Magick::RVG::WORD_SEP` is `/ /`.
:glyph_orientation_vertical
  Applies only when :writing_mode='tb'. This style can have one of four values: 0, 90, 180, 270. The default is 90. This style specifies a rotation on each glyph. With the default value, each glyph is rotated 90 degrees. When :glyph_orientation_vertical=0 each glyph appears in its "normal" (upright) orientation.
:glyph_orientation_horizontal
  Applies only when :writing_mode='lr'. This style can have one of four values: 0, 90, 180, 270. The default is 0. This style specifies a rotation on each glyph. With the default value, each glyph appears in its "normal" (upright) orientation.

#### Examples

:writing_mode='tb'

:writing_mode='lr'

:baseline_shift=>'sub'
:baseline_shift=>'super'