TeX Text

Text in tioga goes to TeX for typesetting: you are not using a partial emulation that is sort-of-like TeX, you are using the real thing.

Since text strings in tioga are passed directly to TeX, you can basically do anything in the text of figures that you can do with text in TeX. The text string can include embedded commands to change font size, family, or whatever. However, more commonly the text string will leave the font selection to a higher level in the document. In tioga it is easy for you to use the "NFSS", TeX's "New Font Selection Scheme" that specifies the font by independently setting family, series, shape, and size. Families include roman, sans serif, and typewriter. Series include medium and bold face. Shapes include upright, italic, slant, and small caps. All these, and the size, are set in the SetTiogaFontInfo command in the TeX file preamble. The tioga defaults for size, family, series, and shape are 10 point roman, medium, and upright. You can change these by means of the attributes tex_fontfamily, tex_fontseries, tex_fontshape, and tex_fontsize. Just like for the tex_preview page and figure sizes, these are given as strings to be copied to the TeX preview file as part of the SetTiogaFontInfo definition.

Text is sized by giving a scale factor relative to a base size. The base size is given by the attribute default_font_size, that is initialized to 10 and can be changed using set_default_font_size. The scale factor is called default_text_scale, is initialized to 1.0, and is changed by rescale_text. When you do a show_text command in tioga, the call can include an additional scale factor. The product of this extra factor times the default_text_scale times the default_font_size determines the size in big points on the output page. At least that is the size the text will have if the output page does not get scaled up or down, and the TeX document does not decide to change things! With text that is being passed to TeX for typesetting, the final decisions are not made until the last moment. See Page_Frame_Bounds for more details.

FigureMaker methods

check_label_clip(x, y) [ doc ]

Returns True if the point given by the figure coordinates
(`x`, `y`) is inside the current label clipping margins.  The
routine `show_label()` uses this to filter out unwanted text
by testing the reference point.  If the point passes this
test, then `show_label()` calls `show_text()`; otherwise, it
simply returns without showing the text.

rescale_text(scale) [ doc ]

Changes the `self.default_text_scale` attribute by multiplying
it bu `scale`.  This also updates the
`self.default_text_height_dx` and
`self.default_text_height_dy` attributes to match the new
setting for `self.default_text_scale`.  See also `rescale()`.

set_default_font_size(size, update_preview_size_string=True) [ doc ]

INPUTS

  size    -- size in points
  update_preview_size_string
          -- see below

Sets the font size in points.  If the
`update_preview_size_string` flag is True, then the
`self.tex_fontsize` attribute will be set to match the new
font size.  The intention is that `set_default_font_size()`
gets called rarely and most font sizing is done using
`rescale_text`.

show_label(text, x, y, scale=1.0, color=None, angle=0.0, alignment=None, justification=None, _skip_log_check=False) [ doc ]

Show a label if inside the label clipping margin

INPUTS

  text    -- str to be processed by TeX
  x       -- x location for reference point
  y       -- y location for reference point

OPTIONAL INPUTS

  color   -- default is to omit color specification
  scale   -- scale relative to default_text_scale.  default 1
  angle   -- degrees to rotate.  default 0
  alignment
          -- see discussion of alignment
  justification
          -- a_justification # see discussion of justification

This method calls `check_label_clip()` with the location for
the text reference point (x, y).  If `check_label_clip()`
returns False, this routine simply returns.  Otherwise, it
passes the input arguments to `show_text()`.

show_text(text, x=None, y=None, side=None, position=None, shift=None, scale=1.0, color=None, angle=0.0, alignment=None, justification=None, _skip_log_check=False) [ doc | example ]

Show a text at specified location

INPUTS

  text    -- str to be processed by TeX
  x       -- x location for reference point
  y       -- y location for reference point
  side    -- Top, Bottom, Left, or Right
  position
          -- fractional distance along side from bottom left
  shift   -- distance away from side in units of text height
  color   -- default is to omit color specification
  scale   -- scale relative to default_text_scale.  default 1
  angle   -- degrees to rotate.  default 0
  alignment
          -- see discussion of alignment
  justification
          -- a_justification # see discussion of justification

This routine takes care of text that is being sent to TeX for
typesetting (see also `show_marker()` for text being used as
graphics and sent directly to PDF).

The location of the reference point for the text can be given
either in figure coordinates (`x` and `y`) or relative to an
edge of the frame (`side`, `position`, and `shift`).

You can optionally provide a color as an RGB triple which will
be used in a `textcolor` command for TeX enclosing the rest of
the text.

The text is scaled by the product of the `scale` entry times
the current value of the `self.default_text_scale` attribute.
It is rotated by the given `angle`.

The reference point can be specified horizontally
(`justification`) and vertically (`alignment`).

The `text` to be sent to TeX can contain anything that TeX
will let you put in a box.  In addition to the usual text and
inline math, you can also do display math, lists, tables, etc.

You can even define your own commands in your TeX preamble and
then use those commands as part of the text in the figure.

NOTE: When entering text for TeX in your Python program, you
will generally want to use the 'r' or 'R' prefix for the
string.  That way, backslashes are treated as normal
characters (except for the two special cases of \' and \\), so
TeX commands using backslashes do not cause trouble.  Without
the prefix, Python uses backslash for a variety of escape
characters such as newline (\n) and tab (\t), so the
backslashes for TeX need to be entered as \\ pairs to be safe.
Compare r"$\nu\sim\tau$" to the equivalent form
"$\\\\nu\\\\sim\\\\tau$" and the incorrect form "$\nu\sim\tau$".

Example

TODO: add a code snippet.

FigureMaker attributes

alignment [ doc ]

Default for text vertical alignment.  Valid settings are
predefined constants: AlignedAtTop, AlignedAtMidheight,
AlignedAtBaseline, and AlignedAtBottom.  See also
`self.justification`.

default_font_size [ doc ]

Default font size in points (relative to the
`self.default_font_size`).  Is initialized to 10.0 and changed
by `set_default_font_size()`.  The intention is that this gets
set rarely and most font sizing is done using
`rescale_text()`.

default_text_height_dx [ doc ]

Height of text having `self.default_text_scale` as measured in
x figure coordinates.

default_text_height_dy [ doc ]

Height of text having `self.default_text_scale` as measured in
y figure coordinates.

default_text_scale [ doc ]

Default factor determining text size (relative to the
`self.default_font_size`).  Is initialized to 1.0 and changed
by `rescale_text()`.

justification [ doc | example ]

Default for text horizontal justification.  Valid settings are
predefined constants: LeftJustified (or Left), Centered, and
RightJustified (or Right).  See also `self.alignment`.

Example

label_bottom_margin [ doc ]

Size of margin on bottom of frame measured as a fraction of
frame height, with positive values corresponding to margins on
the inside of the frame, and negative values to margins on the
outside.  The show_label routine discards text having its
reference point below this position.

label_left_margin [ doc ]

Size of margin on left of frame measured as a fraction of
frame width, with positive values corresponding to margins on
the inside of the frame, and negative values to margins on the
outside.  The `show_label()` routine discards text having its
reference point to the left of this position.

label_right_margin [ doc ]

Size of margin on right of frame measured as a fraction of
frame width, with positive values corresponding to margins on
the inside of the frame, and negative values to margins on the
outside.  The `show_label()` routine discards text having its
reference point to the right of this position.

label_top_margin [ doc ]

Size of margin on top of frame measured as a fraction of frame
height, with positive values corresponding to margins on the
inside of the frame, and negative values to margins on the
outside.  The `show_label()` routine discards text having its
reference point above this position.

text_shift_from_x_origin [ doc ]

Default value for `shift` in `show_yaxis()` when `loc` is AtXOrigin.

text_shift_from_y_origin [ doc ]

Default value for `shift` in `show_xaxis()` when `loc` is AtYOrigin.

text_shift_on_bottom [ doc ]

Default value for `shift` in `show_text()` when `side` is Bottom.

text_shift_on_left [ doc ]

Default value for `shift` in `show_text()` when `side` is Left.

text_shift_on_right [ doc ]

Default value for `shift` in `show_text()` when `side` is Right.

text_shift_on_top [ doc ]

Default value for `shift` in `show_text()` when `side` is Top.

tex_fontfamily [ doc ]

This string will be used as the basic font family
specification in the preview TeX file.  Valid strings include
'rmdefault', 'sfdefault', and 'ttdefault', for roman face,
sans serif face, and typewriter face, respectively.

See also: `self.tex_fontsize`, `self.tex_fontseries`, and
`self.tex_fontshape`.

tex_fontseries [ doc ]

This string will be used as the basic font series
specification in the preview TeX file.  Valid strings include
'mddefault' and 'bfdefault', for medium and bold face,
respectively.

See also: `self.tex_fontsize`, `self.tex_fontfamily`, and
`self.tex_fontshape`.

tex_fontshape [ doc ]

This string will be used as the basic font shape specification
in the preview TeX file.  Valid strings include 'updefault',
'itdefault', 'sldefault', and 'scdefault', for upright,
italic, slant, and small caps, respectively.

See also: `self.tex_fontsize`, `self.tex_fontfamily`, and
`self.tex_fontseries`.

tex_fontsize [ doc ]

This string will be used as the basic font size specification
in the preview TeX file.  Valid strings include things like
'10.0' or '12.0'.

See also: `self.tex_fontfamily`, `self.tex_fontseries`, and
`self.tex_fontshape`.

PyTioga version: alpha (20071021)