Document Solutions for Excel, Java Edition | Document Solutions
Features / Shapes And Pictures / Customize Shape Format and Shape Text
In This Topic
    Customize Shape Format and Shape Text
    In This Topic

    DsExcel not only allows you to add shapes and picture, the library also lets you customize shape formats and shape texts. A user can enhance the look of a shape in the Excel file by changing fill color, formatting three-dimensional orientation or adding lines around the shape.

    Using DsExcel, a user can customize both the shape format and shape text.

    Shape Format

    In DsExcel, you can customize the shape format in three different ways. This includes setting the fill format for the inserted shape using the properties and methods of the IFillFormat interface, configuring the shape's line using the properties and methods of the ILineFormat interface and applying 3D formatting to the shape using the properties and methods of the IThreeDFormat interface.

    Solid Fill

    To format the shape with Solid fill, first you need to use the Solid method of the IFillFormat interface to specify the fill format and then set the setRGB and setTransparency to set the shape's fill color and transparency degree respectively.

    Refer to the following example code to fill the shape with solid fill.

    Java
    Copy Code 
    // Solid fill
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Parallelogram, 1, 1, 200, 100);
shape.getFill().solid();
shape.getFill().getColor().setRGB(Color.GetRed());

    Gradient Fill

    With gradient fill, you can configure the shape fill to the gradient fill using the oneColorGradient method, twoColorGradient method or presetGradient method of the IFillFormat interface.

    After setting the gradient fill, you can insert, delete or change gradient stops; configure the fill style rotation along with the shape and the angle of the gradient fill via the getGradientStops method, setRotateWithObject method and setGradientAngle method of the IFillFormat interface.

    Four types of gradient fills, namely line, radial, rectangular and path are supported by DsExcel. By default, the 'Line' gradient fill is applied.

    Refer to the following example code to fill the shape with gradient fill using presetGradient method.

    Java
    Copy Code 
    // Gradient fill
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Heart, 1, 1, 100, 100);
shape.getFill().presetGradient(GradientStyle.Vertical, 3, PresetGradientType.Silver);
shape.getFill().setRotateWithObject(false);

    Refer to the following example code to fill the shape with gradient fill using twoColorGradient method.

    Java
    Copy Code 
    // Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape
IShape rectangle = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 20, 20, 300, 100);

// Init a two color gradient fill.          
rectangle.getFill().twoColorGradient(GradientStyle.Horizontal, 1);   

//save to an excel file
workbook.save("LineGradient.xlsx");

    To set the radial, rectangular or path gradient fill, you also need to set the PathShapeType along with using the twoColorGradient method.

    Refer to the following example code to fill the shape with 'Radial' gradient fill.

    Java
    Copy Code 
    // Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape
IShape rectangle = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 20, 20, 300, 100);

// Init a two color gradient fill.          
rectangle.getFill().twoColorGradient(GradientStyle.FromCenter, 1);
       
rectangle.getFill().getGradientPathType().equals(PathShapeType.Radial);

//save to an excel file
workbook.save("RadialGradient.xlsx");

    Pattern Fill

    With pattern fill, you can set the shape fill to pattern fill using the patterned method of the IFillFormat interface.

    Further, you can also configure the background color and the pattern color using setObjectThemeColor method of the IColorFormat interface and getPatternColor method of the IFillFormat interface.

    In order to fill the shape with pattern fill, refer to the following example code.

    Java
    Copy Code 
    // Pattern fill
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
shape.getFill().patterned(PatternType.Percent10);
shape.getFill().getColor().setObjectThemeColor(ThemeColor.Accent2);
shape.getFill().getPatternColor().setObjectThemeColor(ThemeColor.Accent6);

    Picture Fill

    In picture fill, you can use the addShape method of the IShapes interface to insert the shape that you want to fill with a picture.

    Also, you can configure the picture format with characteristics like picture height, picture width, brightness, contrast ratio, re-coloring, x-axis and y-axis offset etc using the methods of the IPictureFormat interface.

    In order to fill the shape with picture, refer to the following example code.

    Java
    Copy Code 
    // Add shape of picture type
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 20, 20, 100, 100);
String path = "C:\\Users\\GPCTAdmin\\Pictures\\cat.jpg";

try {
FileInputStream stream = new FileInputStream(path);
shape.getFill().userPicture(stream, ImageType.JPG);
stream.close();
} catch (IOException e) {
e.printStackTrace();
}
// Recolor the picture
shape.getPictureFormat().setColorType(PictureColorType.Grayscale);

// Set picture brightness and contrast ratio
shape.getPictureFormat().setBrightness(0.6);
shape.getPictureFormat().setContrast(0.3);

// Set height, width, x-axis offset and y-axis offset of the specified picture
shape.getPictureFormat().getCrop().setPictureOffsetX(10);
shape.getPictureFormat().getCrop().setPictureOffsetY(-5);
shape.getPictureFormat().getCrop().setPictureWidth(120);
shape.getPictureFormat().getCrop().setPictureHeight(80);

    Texture Fill

    Using texture fill, you can fill the shape with texture of your choice using the presetTextured method of the IFillFormat interface.

    Further, you can also configure the layout of the texture using the setTextureAlignment method, setTextureHorizontalScale method, setTextureOffsetX method, setTextureOffsetY method and setTextureVerticalScale method.

    In order to fill the shape with texture fill, refer to the following example code.

    Java
    Copy Code 
    // Texture Fill
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
shape.getFill().presetTextured(PresetTexture.Canvas);
shape.getFill().setTextureAlignment(TextureAlignment.Center);
shape.getFill().setTextureOffsetX(2.5);
shape.getFill().setTextureOffsetY(3.2);
shape.getFill().setTextureHorizontalScale(0.9);
shape.getFill().setTextureVerticalScale(0.2);
shape.getFill().setTransparency(0.5);

    Line

    Line is a kind of border around the shape. You can create lines around shapes inserted on cells of a spreadsheet using the properties and methods of ILineFormat interface.

    Refer to the following example code to configure the line and line style for the shape.

    Java
    Copy Code 
    // To set shape's line style.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
shape.getLine().setDashStyle(LineDashStyle.Dash);
shape.getLine().setStyle(LineStyle.Single);
shape.getLine().setWeight(2);
shape.getLine().getColor().setObjectThemeColor(ThemeColor.Accent6);
shape.getLine().setTransparency(0.3);

    Shape's Line also supports solid fill, gradient fill and pattern fill and its usage is similar to the Shape Fill.

    3D Formatting

    DsExcel Java enables users to format the three-dimensional layout for the inserted shape via configuring its rotation degree around x, y and z axis. This can be done using the setRotationX method, the setRotationY method and the setRotationZ method of the IThreeDFormat interface.

    In order to apply 3D formatting to the embedded shape, refer to the following example code.

    Java
    Copy Code 
    // To set rotation degree for the shape arround x, y, z axis.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
shape.getThreeD().setRotationX(50);
shape.getThreeD().setRotationY(20);
shape.getThreeD().setRotationZ(30);
shape.getThreeD().setDepth(7);
shape.getThreeD().setZ(20);

    Shape Text

    In DsExcel, you can configure the text and text style for the shape as per your own preferences by using the getTextFrame of the IShape interface.

    Refer to the following example code to configure the text and text style for the inserted shape.

    Java
    Copy Code 
    // To configure the text and text style of the shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 40, 40, 100, 100);
shape.getTextFrame().getTextRange().getFont().getColor().setRGB(Color.FromArgb(0, 255, 0));
shape.getTextFrame().getTextRange().getFont().setBold(true);
shape.getTextFrame().getTextRange().getFont().setItalic(true);
shape.getTextFrame().getTextRange().getFont().setSize(20);
shape.getTextFrame().getTextRange().getFont().setStrikethrough(true);
shape.getTextFrame().getTextRange().getParagraphs().add("This is a rectangle shape.");
shape.getTextFrame().getTextRange().getParagraphs().add("My name is Excel.");
shape.getTextFrame().getTextRange().getParagraphs().get(0).getRuns().add("Hello World!");
shape.getTextFrame().getTextRange().getParagraphs().get(0).getRuns().get(0).getFont().setStrikethrough(false);
shape.getTextFrame().getTextRange().getParagraphs().get(0).getRuns().get(0).getFont().setSize(14);

    Setting text on shape in GcExcel

    Set Formula for Shape Text

    You can set formula for a shape by using setFormula method of the IShape interface. This method configures a formula that refers to text of the range or a defined name. When you set a shape formula for the first time, the shape acquired text and font style of the first cell of the reference. Once shape text has been set, any kind of changes in content of the reference cell updates value of the shape text also. However, font style remains the same.

    Java
    Copy Code 
    // set shape formula to G8
IShape shapeResult = worksheet.getShapes().addShape(AutoShapeType.Rectangle, worksheet.getRange("B7:D8"));
shapeResult.setFormula("=G8");

    You can remove shape reference by setting setFormula method to null. On removing reference, the shape text becomes a custom normal text; shape content gets text of the first cell of removed reference and the font style is the default style. If shape text is removed from the shape, cell reference stops having any affect on the shape text.

    Further, you can also retain formula of the reference shape when exporting to JSON IO, DsExcel API, PDF,HTML, or an image.

    To view the feature in action, see Set Shape Formula demo.

    Set Alignment of Shape Text

    You can align the text in a shape to the left, right, center, distribute, and justify using the setTextAlignment method. Also, you can secure the position of the text frame containing the text at the center using the setHorizontalAnchor method and at the top, middle, and bottom using the setVerticalAnchor method.

    These different alignments and positions of text in a shape can also be exported to PDF documents.

    Align Text

    The setTextAlignment method in ITextRange interface allows you to set the alignment of a text range or a paragraph in a shape using TextAlignmentAnchor enumeration. This method sets the text alignment to left, right, center, distribute, and justify.

    Refer to the following example code to set the alignment of text range and paragraphs in a shape:

    Java
    Copy Code 
    Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 10, 10, 200, 200);

// Add text range and two paragraphs for the shape.
shape.getTextFrame().getTextRange().setText("Text range alignment");
shape.getTextFrame().getTextRange().getParagraphs().add("Aligned to the left");
shape.getTextFrame().getTextRange().getParagraphs().add("Centered");
shape.getTextFrame().getTextRange().getParagraphs().add("Aligned to the right");

// Align text range to the left.
shape.getTextFrame().getTextRange().setTextAlignment(TextAlignmentAnchor.Left);

// Align paragraph to the center.
shape.getTextFrame().getTextRange().getParagraphs().get(2).setTextAlignment(TextAlignmentAnchor.Center);

// Align paragraph to the right.
shape.getTextFrame().getTextRange().getParagraphs().get(3).setTextAlignment(TextAlignmentAnchor.Right);

// Save the workbook in XLSX and PDF formats.
workbook.save("Alignment.xlsx");
workbook.save("Alignment.pdf");

    Anchor Text

    The text frame (or text body) contains the text or paragraph you add to a shape. The setHorizontalAnchor and setVerticalAnchor methods of ITextFrame interface allow you to set the horizontal and vertical anchors of a text frame in a shape using HorizontalAnchor and VerticalAnchor enumerations. The text frame can be positioned horizontally at the center or vertically at the top, middle, or bottom.

    Refer to the following example code to anchor the text frame in a shape:

    Java
    Copy Code 
    // Create a new workbook.
Workbook workbook = new Workbook();

// Fetch default worksheet.
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 10, 10, 300, 300);

// Add two paragraphs for the shape.
shape.getTextFrame().getTextRange().getParagraphs().add("Documents for Excel");
shape.getTextFrame().getTextRange().getParagraphs().add("Middle Centered");

// Centers text vertically.
shape.getTextFrame().setVerticalAnchor(VerticalAnchor.AnchorMiddle);

// Centers text horizontally.
shape.getTextFrame().setHorizontalAnchor(HorizontalAnchor.Center);

// Save workbook.
workbook.save("Alignment.xlsx");
workbook.save("Alignment.pdf");

    You can also set the alignment of a text range and a paragraph, along with the anchor of the text frame in a shape. Refer to the following example code to align and anchor a paragraph at the bottom right:

    Java
    Copy Code 
    Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 10, 10, 300, 300);

// Add a paragraph for the shape.
shape.getTextFrame().getTextRange().getParagraphs().add("Aligned and anchored to bottom right");

// Anchor the text frame to the bottom vertically.
shape.getTextFrame().setVerticalAnchor(VerticalAnchor.AnchorBottom);
        
// Align paragraph to the right.
shape.getTextFrame().getTextRange().getParagraphs().get(0).setTextAlignment(TextAlignmentAnchor.Right);

// Save the workbook in XLSX and PDF formats.
workbook.save("Alignment.xlsx");
workbook.save("Alignment.pdf");

    Note: The TextAlignmentAnchor.Mixed is a special enumeration value returned for a shape having different alignments applied to paragraphs in a text range. If you set the alignment of a text or paragraph in Shape using TextAlignment.Mixed, this will throw an exception.

    Set Direction of Shape Text

    You can set the direction of the text in shape to horizontal, vertical, rotated (to 90 or 270 degree), and stacked (with text reading left-to-right or right to left). The setDirection method in ITextFrame interface allows you to set the direction of the text frame in shape using TextDirection enumeration.

    Refer to the following example code to set the text direction to vertical:

    Java
    Copy Code 
    // Initialize Workbook.
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);

// Add a shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 10, 10, 200, 200);

// Add paragraph for the shape.
shape.getTextFrame().getTextRange().getParagraphs().add("Documents for Excel");
        
// Set the direction of text frame to vertical.
shape.getTextFrame().setDirection(TextDirection.Vertical);

// Save the workbook.
workbook.save("TextDirection.xlsx");

    Set Margin of Shape Text

    You can set the margin of text in a shape in the bottom, left, right and top directions. The setMarginBottom, setMarginLeft, setMarginRight and setMarginTop methods of ITextFrame interface can be used to achieve the same.

    Refer to the following example code which configures the text margins in first shape and keeps it as default in the other.

    Java
    Copy Code 
    //create a new workbook
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);
IShape shape = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 10, 250, 200);
IShape shape2 = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 300, 10, 250, 200);

//set the margin of text
shape.getTextFrame().setMarginBottom(40);
shape.getTextFrame().setMarginTop(40);
shape.getTextFrame().setMarginRight(40);
shape.getTextFrame().setMarginLeft(40);

shape.getTextFrame().getTextRange().getParagraphs().get(0).getRuns().add("Test setting margin for text in a shape");
shape2.getTextFrame().getTextRange().getParagraphs().get(0).getRuns().add("Test input text with default margin");

//save to an excel file
workbook.save("SetMarginOfShapeText.xlsx");

    Setting margin for text on shape in GcExcel