/* ==================================================================== | |
Licensed to the Apache Software Foundation (ASF) under one or more | |
contributor license agreements. See the NOTICE file distributed with | |
this work for additional information regarding copyright ownership. | |
The ASF licenses this file to You under the Apache License, Version 2.0 | |
(the "License"); you may not use this file except in compliance with | |
the License. You may obtain a copy of the License at | |
http://www.apache.org/licenses/LICENSE-2.0 | |
Unless required by applicable law or agreed to in writing, software | |
distributed under the License is distributed on an "AS IS" BASIS, | |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
See the License for the specific language governing permissions and | |
limitations under the License. | |
==================================================================== */ | |
package org.apache.poi.sl.usermodel; | |
import java.util.List; | |
public interface TextShape< | |
S extends Shape<S,P>, | |
P extends TextParagraph<S,P,?> | |
> extends SimpleShape<S,P>, Iterable<P> { | |
/** | |
* Vertical Text Types | |
*/ | |
enum TextDirection { | |
/** | |
* Horizontal text. This should be default. | |
*/ | |
HORIZONTAL, | |
/** | |
* Vertical orientation. | |
* (each line is 90 degrees rotated clockwise, so it goes | |
* from top to bottom; each next line is to the left from | |
* the previous one). | |
*/ | |
VERTICAL, | |
/** | |
* Vertical orientation. | |
* (each line is 270 degrees rotated clockwise, so it goes | |
* from bottom to top; each next line is to the right from | |
* the previous one). | |
* For HSLF: always interpreted by Powerpoint as HORIZONTAL. | |
*/ | |
VERTICAL_270, | |
/** | |
* Determines if all of the text is vertical | |
* ("one letter on top of another"). | |
* For HSLF: not supported | |
*/ | |
STACKED | |
} | |
/** | |
* Specifies alist of auto-fit types. | |
* <p> | |
* Autofit specofies that a shape should be auto-fit to fully contain the text described within it. | |
* Auto-fitting is when text within a shape is scaled in order to contain all the text inside | |
* </p> | |
*/ | |
enum TextAutofit { | |
/** | |
* Specifies that text within the text body should not be auto-fit to the bounding box. | |
* Auto-fitting is when text within a text box is scaled in order to remain inside | |
* the text box. | |
*/ | |
NONE, | |
/** | |
* Specifies that text within the text body should be normally auto-fit to the bounding box. | |
* Autofitting is when text within a text box is scaled in order to remain inside the text box. | |
* | |
* <p> | |
* <em>Example:</em> Consider the situation where a user is building a diagram and needs | |
* to have the text for each shape that they are using stay within the bounds of the shape. | |
* An easy way this might be done is by using NORMAL autofit | |
* </p> | |
*/ | |
NORMAL, | |
/** | |
* Specifies that a shape should be auto-fit to fully contain the text described within it. | |
* Auto-fitting is when text within a shape is scaled in order to contain all the text inside. | |
* | |
* <p> | |
* <em>Example:</em> Consider the situation where a user is building a diagram and needs to have | |
* the text for each shape that they are using stay within the bounds of the shape. | |
* An easy way this might be done is by using SHAPE autofit | |
* </p> | |
*/ | |
SHAPE | |
} | |
/** | |
* This enum represents a compromise for the handling of | |
* HSLF run types (see org.apache.poi.hslf.record.TextHeaderAtom) and | |
* XSLF placeholders (see org.apache.poi.xslf.usermodel.Placeholder). | |
* When a shape is considered a placeholder by the generating application | |
* it can have special properties to alert the user that they may enter content into the shape. | |
* | |
* This enum and the handling around it may change significantly in future releases | |
*/ | |
enum TextPlaceholder { | |
/** Title placeholder shape text */ | |
TITLE, | |
/** Body placeholder shape text */ | |
BODY, | |
/** Center title placeholder shape text */ | |
CENTER_TITLE, | |
/** Center body placeholder shape text */ | |
CENTER_BODY, | |
/** Half-sized body placeholder shape text */ | |
HALF_BODY, | |
/** Quarter-sized body placeholder shape text */ | |
QUARTER_BODY, | |
/** Notes placeholder shape text */ | |
NOTES, | |
/** Any other text */ | |
OTHER | |
} | |
/** | |
* Returns the text contained in this text frame, which has been made safe | |
* for printing and other use. | |
* | |
* @return the text string for this textbox. | |
* | |
* @since POI 3.14-Beta2 | |
*/ | |
String getText(); | |
/** | |
* Sets (overwrites) the current text. | |
* Uses the properties of the first paragraph / textrun. | |
* Text paragraphs are split by \\r or \\n. | |
* New lines within text run are split by \\u000b | |
* | |
* @param text the text string used by this object. | |
* | |
* @return the last text run of the - potential split - text | |
*/ | |
TextRun setText(String text); | |
/** | |
* Adds the supplied text onto the end of the TextParagraphs, | |
* creating a new RichTextRun for it to sit in. | |
* | |
* @param text the text string to be appended. | |
* @param newParagraph if true, a new paragraph will be added, | |
* which will contain the added text | |
* | |
* @since POI 3.14-Beta1 | |
*/ | |
TextRun appendText(String text, boolean newParagraph); | |
/** | |
* @return the TextParagraphs for this text box | |
*/ | |
List<? extends TextParagraph<S,P,?>> getTextParagraphs(); | |
/** | |
* @return text shape margin | |
*/ | |
Insets2D getInsets(); | |
/** | |
* Sets the shape margins | |
* | |
* @param insets the new shape margins | |
*/ | |
void setInsets(Insets2D insets); | |
/** | |
* Compute the cumulative height occupied by the text | |
*/ | |
double getTextHeight(); | |
/** | |
* Returns the type of vertical alignment for the text. | |
* | |
* @return the type of vertical alignment | |
*/ | |
VerticalAlignment getVerticalAlignment(); | |
/** | |
* Sets the type of vertical alignment for the text. | |
* | |
* @param vAlign - the type of alignment. | |
* A {@code null} values unsets this property. | |
*/ | |
void setVerticalAlignment(VerticalAlignment vAlign); | |
/** | |
* Returns if the text is centered. | |
* If true and if the individual paragraph settings allow it, | |
* the whole text block will be displayed centered, i.e. its left and right | |
* margin will be maximized while still keeping the alignment of the paragraphs | |
* | |
* @return true, if the text anchor is horizontal centered | |
*/ | |
boolean isHorizontalCentered(); | |
/** | |
* Sets if the paragraphs are horizontal centered | |
* | |
* @param isCentered true, if the paragraphs are horizontal centered | |
* A {@code null} values unsets this property. | |
*/ | |
void setHorizontalCentered(Boolean isCentered); | |
/** | |
* @return whether to wrap words within the bounding rectangle | |
*/ | |
boolean getWordWrap(); | |
/** | |
* @param wrap whether to wrap words within the bounding rectangle | |
*/ | |
void setWordWrap(boolean wrap); | |
/** | |
* @return vertical orientation of the text | |
*/ | |
TextDirection getTextDirection(); | |
/** | |
* sets the vertical orientation | |
* @param orientation vertical orientation of the text | |
*/ | |
void setTextDirection(TextDirection orientation); | |
/** | |
* The text rotation can be independent specified from the shape rotation. | |
* For XSLF this can be an arbitrary degree, for HSLF the degree is given in steps of 90 degrees | |
* | |
* @return text rotation in degrees, returns null if no rotation is given | |
*/ | |
Double getTextRotation(); | |
/** | |
* Sets the text rotation. | |
* For XSLF this can ben an arbitrary degree, for HSLF the rotation is rounded to next 90 degree step | |
* | |
* @param rotation the text rotation, or null to unset the rotation | |
*/ | |
void setTextRotation(Double rotation); | |
/** | |
* Sets the text placeholder | |
*/ | |
void setTextPlaceholder(TextPlaceholder placeholder); | |
/** | |
* @return the text placeholder | |
*/ | |
TextPlaceholder getTextPlaceholder(); | |
} |