Documents for Excel, .NET 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 Color property and Transparency property to set the shape's fill color and transparency degree respectively.

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

    C#
    Copy Code
    //Solid Fill
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Balloon, 10, 10, 100, 100);
    IColorFormat color = shape.Fill.Color;
    color.RGB = Color.Red;
    shape.Fill.Solid();

    Gradient Fill

    Gradient fill is a graphical effect which provides the 3D color look as one color blends into another. In gradient fill, you first need to set the shape fill to the gradient fill using the OneColorGradient methodTwoColorGradient method or PresetGradient method of the IFillFormat interface. When you're done, you can then insert, delete or modify gradient stops; set the fill style rotation along with the shape and the angle of the gradient fill using the GradientStops propertyRotateWithObject property and GradientAngle property 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.

    C#
    Copy Code
    //Gradient Fill
    IShape shape1 = worksheet.Shapes.AddShape(AutoShapeType.Heart, 120, 10, 100, 100);
    shape1.Fill.PresetGradient(GradientStyle.Vertical, 3, PresetGradientType.Silver);
    shape1.Fill.RotateWithObject = false;

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

    C#
    Copy Code
    // Initialize workbook
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.Worksheets[0];
    
    // Add a shape
    IShape rectangle = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 20, 20, 300, 100);
    
    // Init a two color gradient fill         
    rectangle.Fill.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 GradientPathType along with using the TwoColorGradient method.

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

    C#
    Copy Code
    // Initialize workbook
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.Worksheets[0];
    
    // Add a shape
    IShape rectangle = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 20, 20, 300, 100);
    
    // Init a two color gradient fill        
    rectangle.Fill.TwoColorGradient(GradientStyle.FromCenter, 1);
    
    // Set gradient path type
    rectangle.Fill.GradientPathType = PathShapeType.Radial;
    
    //save to an excel file
    workbook.Save("RadialGradient.xlsx");

    Pattern Fill

    In pattern fill, you first need to set the shape fill to pattern fill using the Patterned method of the IFillFormat interface. Afterwards, you can set the background color and the pattern color using Color property and PatternColor property of the IFillFormat interface.

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

    C#
    Copy Code
    //Pattern Fill
    IShape shape2 = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 240, 10, 100, 100);
    shape2.Fill.Patterned(GrapeCity.Documents.Excel.Drawing.PatternType.Percent10);
    shape2.Fill.Color.ObjectThemeColor = ThemeColor.Accent2;
    shape2.Fill.PatternColor.ObjectThemeColor = ThemeColor.Accent6;

    Picture Fill

    In picture fill, you can use the AddShape method of the IShapes interface to first add the shape that you want to fill with a picture. Further, you can also set the picture format including characteristics like picture height, picture width, brightness, contrast ratio, re-coloring, x-axis and y-axis offset etc using the properties of the IPictureFormat interface.

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

    C#
    Copy Code
    // Add shape of picture type
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 20, 20, 100, 100);
    string path = @"Images\flower.jpg";
    FileStream stream = System.IO.File.Open(path, FileMode.Open);
    shape.Fill.UserPicture(stream, ImageType.JPG);
    stream.Dispose();
    // Recolor the picture
    shape.PictureFormat.ColorType = PictureColorType.Grayscale;
    // Set picture's brightness and contrast ratio.
    shape.PictureFormat.Brightness = 0.6;
    shape.PictureFormat.Contrast = 0.3;
    // Set height, width, x-axis offset and y-axis offset of the specified picture.
    shape.PictureFormat.Crop.PictureOffsetX = 10;
    shape.PictureFormat.Crop.PictureOffsetY = -5;
    shape.PictureFormat.Crop.PictureWidth = 120;
    shape.PictureFormat.Crop.PictureHeight = 80;

    Texture Fill

    In texture fill, you can fill the shape with texture using the PresetTextured method, or UserTextured method of the IFillFormat interface. Further, you can also use the TextureAlignment propertyTextureHorizontalScale propertyTextureOffsetX propertyTextureOffsetY property and TextureVerticalScale property to configure the layout of the texture.

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

    C#
    Copy Code
    //Texture Fill
    IShape shape3 = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 360, 10, 100, 100);
    shape3.Fill.PresetTextured(PresetTexture.Canvas);
    shape3.Fill.TextureAlignment = TextureAlignment.Center;
    shape3.Fill.TextureOffsetX = 2.5;
    shape3.Fill.TextureOffsetY = 3.2;
    shape3.Fill.TextureHorizontalScale = 0.9;
    shape3.Fill.TextureVerticalScale = 0.2;
    shape3.Fill.Transparency = 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.

    C#
    Copy Code
    // To set shape's line style.
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 10, 10, 100, 100);
    shape.Line.DashStyle = LineDashStyle.Dash;
    shape.Line.Style = LineStyle.Single;
    shape.Line.Weight = 2;
    shape.Line.Color.ObjectThemeColor = ThemeColor.Accent6;
    shape.Line.Transparency = 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 allows you to format the three-dimensional layout for the inserted shape by setting its rotation degree around x,y and z axis.

    Refer to the following example code to apply 3D formatting to the embedded shape.

    C#
    Copy Code
    // To set shape's rotation degree arround x, y, z axis.
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 50, 10, 100, 100);
    shape.ThreeD.RotationX = 50;
    shape.ThreeD.RotationY = 20;
    shape.ThreeD.RotationZ = 30;
    shape.ThreeD.Depth = 7;
    shape.ThreeD.Z = 20;

    Shape Text

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

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

    C#
    Copy Code
    // To config shape's text and text style.
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 40, 40, 100, 100);
    shape.TextFrame.TextRange.Font.Color.RGB = System.Drawing.Color.FromArgb(0, 255, 0);
    shape.TextFrame.TextRange.Font.Bold = true;
    shape.TextFrame.TextRange.Font.Italic = true;
    shape.TextFrame.TextRange.Font.Size = 20;
    shape.TextFrame.TextRange.Font.Strikethrough = true;
    
    shape.TextFrame.TextRange.Paragraphs.Add("This is a rectangle shape.");
    shape.TextFrame.TextRange.Paragraphs.Add("My name is GcExcel.");
    shape.TextFrame.TextRange.Paragraphs[1].Runs.Add("Hello World!");
    
    shape.TextFrame.TextRange.Paragraphs[1].Runs[0].Font.Strikethrough = false;
    shape.TextFrame.TextRange.Paragraphs[1].Runs[0].Font.Size = 35;

    You can also set the alignment and position of text on shape by using the HorizontalAnchor and VerticalAnchor 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.

    C#
    Copy Code
    Workbook workbook = new Workbook();
    IWorksheet worksheet = workbook.Worksheets[0];
    
    //Add a shape.
    IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 10, 10, 300, 300);
    
    //Add two paragraphs for the shape.
    shape.TextFrame.TextRange.Paragraphs.Add("GrapeCity Documents for Excel");
    shape.TextFrame.TextRange.Paragraphs.Add("Middle Centered");
    
    //Centers text vertically.
    shape.TextFrame.VerticalAnchor = VerticalAnchor.AnchorMiddle;
    //Centers text horizontally.
    shape.TextFrame.HorizontalAnchor = HorizontalAnchor.Center;
    
    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.