[vtk-developers] new vtkTextProperty class and changes

[Sebastien BARRE]

Hey Folk,

I've recently added the vtkTextProperty class:
http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html

I'll wait a couple of days for developers comments then post this summary 
to the users list and FAQ.

Here follows: Description, Backward compatibility issues, List of new 
vtkTextProperty (class by class), API additions.

Description
=========

This class factorizes the font attributes that used to be spread out and 
duplicated in at 10 different classes (actors and mappers):
   - font family, size, bold, italic, shadow, horizontal and vertical 
justification ;
   - line spacing (still not supported, it wasn't before either) ;
   - line offset (no change to line offset either, i.e. stay away from line 
offset if you use multiline text) ;
   - new: color and opacity ;
   - new: antialiasing hint flag (will be honored by mappers or not).

I tried to make sure you can use a vtkTextProperty in the same way a 
vtkProperty can be used, i.e. you should be able to share a text prop 
between different actors or assign the same text prop to an actor that is 
controlled by more than one (vtkXYPlot for example). In a reasonable way :)

Backward compatibility issues:
=========

The Color and Opacity attributes of the text are now controlled by the 
vtkTextProperty instead of the actor2D.
     Thus, instead of:
	actor->GetProperty()->SetColor(...)
	actor->GetProperty()->SetOpacity(...)
     you would do:
	actor->GetTextProperty()->SetColor(...)
	actor->GetTextProperty()->SetOpacity(...)

To make things easier for the moment I've set the text prop default color 
to (-1.0, -1.0, -1.0) and the default opacity to -1.0. These values are 
checked by the text mappers and if they are found, the mappers will use the 
color and opacity of the Actor2D instead.

List of new vtkTextProperty (class by class):
=========

vtkTextMapper (Rendering)
   - you can still use a vtkTextMapper + vtkActor2D combination, but I 
would advise you to use a single vtkTextActor instead, this will give you 
maximum flexibility.
   - has 1 text prop: TextProperty, but although you have access to it, do 
not play with it unless you are using vtkTextMapper with a vtkActor2D. In 
all other cases, use the text prop provided by the actor (see below)

vtkTextActor (Rendering):
   - has 1 text prop: TextProperty.

vtkScalarBarActor (Rendering):
   - has 2 text props: TitleTextProperty, LabelTextProperty ;
   - the way the sizes of the text elements were computed has been 
optimized, a typical example like Rendering/Testing/Tcl/ScalarBar.tcl is 
now 4 to 5 times faster.

vtkAxisActor2D (Rendering)
   - has 2 text props: TitleTextProperty, LabelTextProperty ;
   - fixed (potential) bug in labels size computation

vtkParallelCoordinatesActor  (Rendering)
   - has 2 text props: TitleTextProperty, LabelTextProperty (note that 
since there are no axes titles, there is not text prop for them) ;
   - fixed build time issues (was rendering too often)

vtkLabeledDataMapper (Rendering)
   - has 1 text prop: LabelTextProperty.

vtkCaptionActor2D (Hybrid)
   - has 1 text prop: CaptionTextProperty.

vtkLegendBoxActor (Hybrid)
   - has 1 text prop: EntryTextProperty (its color attribute is ignored if 
a legend entry's color has been set explicitly).
   - code has been fixed (the text attributes were indeed ignored in the 
previous implem)

vtkXYPlotActor
   - has 3 text prop: TitleTextProperty (plot title), 
AxisTitleTextProperty, AxisLabelTextProperty (title and labels of all axes)
   - the legend box text prop (i.e. entry text prop) can be retrieved 
through actor->GetLegendBoxActor()->GetEntryTextProperty()
   - the X (or Y) axis text props (i.e. title and label text props) can be 
retrieved through actor->GetX/YAxisActor2D->GetTitle/LabelTextProperty(), 
and will override the corresponding AxisTitleTextProperty or 
AxisLabelTextProperty props as long as they remain untouched.

vtkCubeAxesActor2D
   - has 2 text props: AxisTitleTextProperty, AxisLabelTextProperty (title 
and label of all axes)
   - the X (Y or Z) axis text props (i.e. title and label text props) can 
be retrieved through 
actor->GetX/Y/ZAxisActor2D->GetTitle/LabelTextProperty(), and will override 
the corresponding AxisTitleTextProperty or AxisLabelTextProperty props as 
long as they remain untouched.

API additions
=========

Many of these actors had duplicated (and sometimes slightly different) ways 
to make a text fit/constrained into a rectangle. I've tried to 
move/factorize this code in the following 2 methods. Feel free to use them 
in the future. This code has been optimized (bisection start point) 
resulting in an overall speedup for all actors.

   // Description:
   // Set and return the font size required to make this mapper fit in a given
   // target rectangle (width * height, in pixels).
   virtual int SetConstrainedFontSize(vtkViewport*,
                                      int targetWidth, int targetHeight);

   // Description:
   // Set and return the font size required to make each element of an array of
   // mappers fit in a given rectangle (width * height, in pixels).
   // This font size is the smallest size that was required to fit the largest
   // mapper in this constraint.
   // The resulting maximum area of the mappers is also returned.
   static int SetMultipleConstrainedFontSize(vtkViewport*,
                                             int targetWidth, int targetHeight,
                                             vtkTextMapper** mappers,
                                             int nbOfMappers,
                                             int* maxResultingSize);

Thanks

--
Sebastien Barre