net.sf.jasperreports.engine.JRCommonText Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
JasperReports Library
There is a newer version: 7.0.1
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2023 Cloud Software Group, Inc. All rights reserved.
 * http://www.jaspersoft.com
 *
 * Unless you have purchased a commercial license agreement from Jaspersoft,
 * the following license terms apply:
 *
 * This program is part of JasperReports.
 *
 * JasperReports is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JasperReports is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with JasperReports. If not, see .
 */
package net.sf.jasperreports.engine;

import net.sf.jasperreports.engine.type.RotationEnum;

/**
 * Common interface of design and print text elements.
 * 
 * There are two kinds of text elements in JasperReports: static texts and text fields. As
 * their names suggest, the first are text elements with fixed, static content, they do not
 * change during the report-filling process, and they are used especially for introducing
 * labels into the final document. Text fields, however, have an associated expression that is
 * evaluated at runtime to produce the text content that will be displayed. Both types of text
 * elements share some properties, and those are introduced using a <textElement> tag.
 * 
Rotating Text
 * The rotation attribute (see {@link #getRotationValue()}), available for text elements, 
 * allows changing the text direction by rotating it 90 degrees to the right or to the left, or by 
 * rotating it 180 degrees to be rendered upside down. Possible values are:
 * 
 * None - this is the default value
 * Left
 * Right
 * UpsideDown
 * 
 * Text Markup
 * Normally, all the text content in a text element has the style specified by the text element
 * attributes (text fore color, text background color, font name, font size, etc.). But in some
 * cases, users will want to highlight a few words inside a text element, usually by changing
 * the text fore color, changing the font style using an underline, or by making it bold or
 * italic. In such cases, the text content of that particular text element will no longer be pure
 * text. It will be specially structured XML content that includes style information in the
 * text itself, or some other form of markup language.
 * 
 * All text elements have an option attribute called markup (see {@link #getMarkup()}) 
 * which can be used to specified the type of markup language that will be used inside the text element, 
 * to format its content.
 * 

 * The following are the predefined values possible for the markup attribute:
 * 

 * none - There are no markup tags. The content of the text element is plain text.This is the default value.
 * styled - The content of the text element is styled text, an proprietary XML type of markup text described below.
 * html - The content of the text element is Hyper Text Markup Language.
 * rtf - The content of the text element is Rich Text Format.
 * 
 * Styled Text
 * The JasperReports proprietary markup language is called styled text and is an XML
 * based format in which the style of any portion of text inside a text element can be
 * changed by embedding that portion inside a <style> tag or other simple HTML tag
 * from the following list: <b>, <u>, <i>, 
 * <font>, <sup>, <sub>, <li>, or <br>. As
 * already mentioned, for styled text elements, the content is considered XML, and the
 * engine tries to parse it to extract the style information at runtime. If the parsing fails for
 * any reason, including malformed XML tags, then the engine will simply render that
 * content as pure text, not styled text.
 * 
 * The XML structure of styled text is very simple and consists only of embedded <style>
 * tags and simple HTML tags. Those tags can be nested on an unlimited number of levels
 * to override certain style settings for the embedded text.
 * 

 * The <style> tag has various attributes for altering the color, font, or other style
 * properties of the text. From the standard HTML <font> tag, only the fontFace, 
 * color and size attributes are recognized by the JasperReports engine.
 * 

 * All style attributes inside a <style> or <font> 
 * tag are optional because each individual style property is inherited from the overall 
 * text element or from the parent <style> tag when nested <style> 
 * tags are used. Special XML characters like &, <, >, ", and ' must be XML-encoded when placed 
 * inside a text field.
 * 
 * To see how the markup and styled text features work in JasperReports, check the
 * /demo/samples/markup sample provided with the project source files.
 * 
 * @author Lucian Chirita ([email protected])
 */
public interface JRCommonText extends JRCommonElement, JRBoxContainer, JRParagraphContainer
{
	/**
	 * 
	 */
	public static final String MARKUP_NONE = "none";
	public static final String MARKUP_STYLED_TEXT = "styled";
	public static final String MARKUP_HTML = "html";
	public static final String MARKUP_RTF = "rtf";

	/**
	 * Gets the text rotation.
	 * @return a value representing one of the text rotation constants in {@link RotationEnum}
	 */
	public RotationEnum getRotationValue();
	
	/**
	 * Gets the text own rotation.
	 * @return a value representing one of the text rotation constants in {@link RotationEnum}
	 */
	public RotationEnum getOwnRotationValue();
	
	/**
	 * Sets the text rotation.
	 * @param rotationEnum a value representing one of the text rotation constants in {@link RotationEnum}
	 */
	public void setRotation(RotationEnum rotationEnum);
	
	/**
	 * Returns the text markup.
	 */
	public String getMarkup();

	public String getOwnMarkup();
	
	public void setMarkup(String markup);

	float getFontsize();
	
}