Documents for Excel, Java Edition Documentation
Features / Shapes And Pictures / Customize Shape Format and Shape Text
In This Topic
    Customize Shape Format and Shape Text
    In This Topic

    GcExcel 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 GcExcel, a user can customize both the shape format and shape text. 

    Shape Format

    In GcExcel, 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 GcExcel. 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

    GcExcel 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 GcExcel, 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 xxx.");
    shape.getTextFrame().getTextRange().getParagraphs().get(1).getRuns().add("Hello World!");
    shape.getTextFrame().getTextRange().getParagraphs().get(1).getRuns().get(0).getFont().setStrikethrough(false);
    shape.getTextFrame().getTextRange().getParagraphs().get(1).getRuns().get(0).getFont().setSize(35);

    You can also set the alignment and position of text on shape by using the setHorizontalAnchor and setVerticalAnchor properties of ITextFrame interface. These properties configure the horizontal and vertical alignment of text on shape.

    Further, the HorizontalAnchor and VerticalAnchor enumerations specify the position of text in the text frame. The text can be placed horizontally at the center or vertically at top, middle or bottom.

    These different alignments and positions of text on shape can also be exported to PDF document.

    Refer to the following example code to configure the alignment and position of text on 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("GrapeCity 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"); 

    Note: The right alignment for text on shape is not supported in GcExcel as it is not supported in Excel.