Documents for Excel, Java Edition Documentation
Features / Shapes And Pictures
In This Topic
    Shapes And Pictures
    In This Topic

    GcExcel Java allows users to insert drawing objects like shapes and pictures on cells of a spreadsheet.

    You can draw and insert arrows, lines, pictures and general shapes of your choice based on the specific requirements.

    GcExcel allows users to insert and customize shapes and pictures on cells of a worksheet. You can work with shape and picture by accessing the properties and methods of the IShape interface and the IShapes interface.

    With GcExcel library, you can create different shape types such as Connector, Shape and Picture.

    Connector

    A connector is used when you need to connect or disconnect two general shapes. In GcExcel, you can use the BeginConnect method, EndConnect method, BeginDisconnect method and EndDisconnect method of the IConnectorFormat interface to attach and detach the ends of the connector to other shapes.

    Refer to the following example code to connect general shapes using the connector format.

    Java
    Copy Code
    // To configure the connector shape
    IShape ShapeBegin = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
    IShape EndBegin = worksheet.getShapes().addShape(AutoShapeType.Rectangle, 200, 200, 100, 100);
    IShape ConnectorShape = worksheet.getShapes().addConnector(ConnectorType.Straight, 1, 1, 101, 101);
            
    // To detach the ends of the connector to other shapes
    ConnectorShape.getConnectorFormat().beginConnect(ShapeBegin, 3);
    ConnectorShape.getConnectorFormat().endConnect(EndBegin, 0);

    Note: One of the limitations of using connector format is that you can add a connector to connect two general shapes and export it but the connector will be shown only after you drag the shape to your spreadsheet.

    Shape

    A shape is a drawing object and a member of the Shapes collection. In GcExcel, the Shapes collection represents the collection of shapes in a specified worksheet. All the drawing objects including chart, comment, picture, slicer, general shape and shape group are defined as Shape.

    A name can also be assigned to a shape, be it a chart, picture, connector or any autoshape, by using different methods provided in IShapes interface. By assigning a name to a shape, it be directly accessed and its properties can be modified rather than traversing through the list of all shapes.

    Refer to the below example code to assign a name to an autoshape.

    Java
    Copy Code
      // create a new workbook
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.getWorksheets().get(0);
    
    // Create shape with custom name
    IShape shape = worksheet.getShapes().addShape("Custom Name to Balloon Shape", AutoShapeType.Balloon, 50, 50, 100, 200);
    
    // Get shape by custom name
    IShape balloonShape = worksheet.getShapes().get("Custom Name to Balloon Shape");
    balloonShape.getFill().getColor().setRGB(Color.GetGreen());
    
    // save to an excel file
    workbook.save("BalloonShape.xlsx");
    

    Refer to the below example code to assign a name to a chart.

    Java
    Copy Code
           // create a new workbook
         Workbook workbook = new Workbook();
         // Fetch default worksheet
         IWorksheet worksheet = workbook.getWorksheets().get(0);
         IShape shape = worksheet.getShapes().addChart("Area Chart with CustomName", ChartType.Area, 250, 20, 360, 230);
         worksheet.getRange("A1:C13").setValue(new Object[][] {
        { null, "Blue Series", "Orange Series" },
        { "Jan", 0, 59.1883603948205 },
        { "Feb", 44.6420211591501, 52.2280901938606 },
        { "Mar", 45.2174930051225, 49.8093056416248 },
        { "Apr", 62, 37.3065749226828 },
        { "May", 53, 34.4312192530766 },
        { "Jun", 31.8933622049831, 69.7834561753736 },
        { "Jul", 41.7930895085093, 63.9418103906982 },
        { "Aug", 73, 57.4049534494926 },
        { "Sep", 49.8773891668518, 33 },
        { "Oct", 50, 74 },
        { "Nov", 54.7658428630216, 22.9587876597096 },
        { "Dec", 32, 54 },
    });
    
         //Get chart by custom name
         IShape areaChart = worksheet.getShapes().get("Area Chart with CustomName");
         areaChart.getChart().getSeriesCollection().add(worksheet.getRange("A1:C13"), RowCol.Columns);
         areaChart.getChart().getChartTitle().setText("Area Chart");
    
         //save to an excel file
         workbook.save("ChartName.xlsx");
    

    Picture

    You can insert pictures on cells of a spreadsheet by using the AddPicture method of the IShapes interface. The IPictureFormat interface in GcExcel allows users to customize and format pictures while working in a spreadsheet.

    Refer to the following example code when working with picture in GcExcel:

    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);

    Refer to the below example code to assign a name to a picture.

    Java
    Copy Code
          // create a new workbook
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.getWorksheets().get(0);
    
    // Create shape with custom name
    IShape shape = worksheet.getShapes().addPicture("Custom Name to Image", "image.png", 10, 10, 250, 150);
    
    // Get the picture name
    System.out.println(shape.getName().toString());
    
    // save to an excel file
    workbook.save("PictureName.xlsx");
    

    Working with shapes and pictures in the GcExcel library involves the following tasks:

    Customize Shape Format and Shape Text

    Hyperlink on Shape

    Group or Ungroup Shapes

    Shape Adjustment

    Background Image

    Size and Position of Image

    See Also