This closes #1169, initialize add form controls supported (#1181)

- Breaking changes:
* Change
    `func (f *File) AddShape(sheet, cell string, opts *Shape) error`
    to
    `func (f *File) AddShape(sheet string, opts *Shape) error`
* Rename the `Runs` field to `Paragraph` in the exported `Comment` data type
- Add new exported function `AddFormControl` support to add button and radio form controls
- Add check for shape type for the `AddShape` function, an error will be returned if no shape type is specified
- Updated functions documentation and the unit tests

excelize_test.go

@@ -383,15 +383,6 @@ func TestNewFile(t *testing.T) {
 	assert.NoError(t, f.Save())
 }
 
-func TestAddDrawingVML(t *testing.T) {
-	// Test addDrawingVML with illegal cell reference
-	f := NewFile()
-	assert.EqualError(t, f.addDrawingVML(0, "", "*", 0, 0), newCellNameToCoordinatesError("*", newInvalidCellNameError("*")).Error())
-
-	f.Pkg.Store("xl/drawings/vmlDrawing1.vml", MacintoshCyrillicCharset)
-	assert.EqualError(t, f.addDrawingVML(0, "xl/drawings/vmlDrawing1.vml", "A1", 0, 0), "XML syntax error on line 1: invalid UTF-8")
-}
-
 func TestSetCellHyperLink(t *testing.T) {
 	f, err := OpenFile(filepath.Join("test", "Book1.xlsx"))
 	assert.NoError(t, err)
@@ -978,7 +969,7 @@ func TestSetDeleteSheet(t *testing.T) {
 		f, err := prepareTestBook4()
 		assert.NoError(t, err)
 		assert.NoError(t, f.DeleteSheet("Sheet1"))
-		assert.NoError(t, f.AddComment("Sheet1", Comment{Cell: "A1", Author: "Excelize", Runs: []RichTextRun{{Text: "Excelize: ", Font: &Font{Bold: true}}, {Text: "This is a comment."}}}))
+		assert.NoError(t, f.AddComment("Sheet1", Comment{Cell: "A1", Author: "Excelize", Paragraph: []RichTextRun{{Text: "Excelize: ", Font: &Font{Bold: true}}, {Text: "This is a comment."}}}))
 		assert.NoError(t, f.SaveAs(filepath.Join("test", "TestSetDeleteSheet.TestBook4.xlsx")))
 	})
 }

shape.go

@@ -22,6 +22,9 @@ func parseShapeOptions(opts *Shape) (*Shape, error) {
 	if opts == nil {
 		return nil, ErrParameterInvalid
 	}
+	if opts.Type == "" {
+		return nil, ErrParameterInvalid
+	}
 	if opts.Width == 0 {
 		opts.Width = defaultShapeSize
 	}
@@ -285,7 +288,7 @@ func parseShapeOptions(opts *Shape) (*Shape, error) {
 //	wavy
 //	wavyHeavy
 //	wavyDbl
-func (f *File) AddShape(sheet, cell string, opts *Shape) error {
+func (f *File) AddShape(sheet string, opts *Shape) error {
 	options, err := parseShapeOptions(opts)
 	if err != nil {
 		return err
@@ -313,7 +316,7 @@ func (f *File) AddShape(sheet, cell string, opts *Shape) error {
 		f.addSheetDrawing(sheet, rID)
 		f.addSheetNameSpace(sheet, SourceRelationship)
 	}
-	if err = f.addDrawingShape(sheet, drawingXML, cell, options); err != nil {
+	if err = f.addDrawingShape(sheet, drawingXML, opts.Cell, options); err != nil {
 		return err
 	}
 	return f.addContentTypePart(drawingID, "drawings")

shape_test.go

@@ -12,18 +12,19 @@ func TestAddShape(t *testing.T) {
 	if !assert.NoError(t, err) {
 		t.FailNow()
 	}
-	shape := &Shape{
+	assert.NoError(t, f.AddShape("Sheet1", &Shape{
+		Cell: "A30",
 		Type: "rect",
 		Paragraph: []RichTextRun{
 			{Text: "Rectangle", Font: &Font{Color: "CD5C5C"}},
 			{Text: "Shape", Font: &Font{Bold: true, Color: "2980B9"}},
 		},
-	}
-	assert.NoError(t, f.AddShape("Sheet1", "A30", shape))
-	assert.NoError(t, f.AddShape("Sheet1", "B30", &Shape{Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}))
-	assert.NoError(t, f.AddShape("Sheet1", "C30", &Shape{Type: "rect"}))
-	assert.EqualError(t, f.AddShape("Sheet3", "H1",
+	}))
+	assert.NoError(t, f.AddShape("Sheet1", &Shape{Cell: "B30", Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}))
+	assert.NoError(t, f.AddShape("Sheet1", &Shape{Cell: "C30", Type: "rect"}))
+	assert.EqualError(t, f.AddShape("Sheet3",
 		&Shape{
+			Cell: "H1",
 			Type: "ellipseRibbon",
 			Line: ShapeLine{Color: "4286F4"},
 			Fill: Fill{Color: []string{"8EB9FF"}},
@@ -41,15 +42,24 @@ func TestAddShape(t *testing.T) {
 			},
 		},
 	), "sheet Sheet3 does not exist")
-	assert.EqualError(t, f.AddShape("Sheet3", "H1", nil), ErrParameterInvalid.Error())
-	assert.EqualError(t, f.AddShape("Sheet1", "A", shape), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
+	assert.EqualError(t, f.AddShape("Sheet3", nil), ErrParameterInvalid.Error())
+	assert.EqualError(t, f.AddShape("Sheet1", &Shape{Cell: "A1"}), ErrParameterInvalid.Error())
+	assert.EqualError(t, f.AddShape("Sheet1", &Shape{
+		Cell: "A",
+		Type: "rect",
+		Paragraph: []RichTextRun{
+			{Text: "Rectangle", Font: &Font{Color: "CD5C5C"}},
+			{Text: "Shape", Font: &Font{Bold: true, Color: "2980B9"}},
+		},
+	}), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
 	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestAddShape1.xlsx")))
 
 	// Test add first shape for given sheet
 	f = NewFile()
 	lineWidth := 1.2
-	assert.NoError(t, f.AddShape("Sheet1", "A1",
+	assert.NoError(t, f.AddShape("Sheet1",
 		&Shape{
+			Cell: "A1",
 			Type: "ellipseRibbon",
 			Line: ShapeLine{Color: "4286F4", Width: &lineWidth},
 			Fill: Fill{Color: []string{"8EB9FF"}},
@@ -69,16 +79,23 @@ func TestAddShape(t *testing.T) {
 		}))
 	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestAddShape2.xlsx")))
 	// Test add shape with invalid sheet name
-	assert.EqualError(t, f.AddShape("Sheet:1", "A30", shape), ErrSheetNameInvalid.Error())
+	assert.EqualError(t, f.AddShape("Sheet:1", &Shape{
+		Cell: "A30",
+		Type: "rect",
+		Paragraph: []RichTextRun{
+			{Text: "Rectangle", Font: &Font{Color: "CD5C5C"}},
+			{Text: "Shape", Font: &Font{Bold: true, Color: "2980B9"}},
+		},
+	}), ErrSheetNameInvalid.Error())
 	// Test add shape with unsupported charset style sheet
 	f.Styles = nil
 	f.Pkg.Store(defaultXMLPathStyles, MacintoshCyrillicCharset)
-	assert.EqualError(t, f.AddShape("Sheet1", "B30", &Shape{Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}), "XML syntax error on line 1: invalid UTF-8")
+	assert.EqualError(t, f.AddShape("Sheet1", &Shape{Cell: "B30", Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}), "XML syntax error on line 1: invalid UTF-8")
 	// Test add shape with unsupported charset content types
 	f = NewFile()
 	f.ContentTypes = nil
 	f.Pkg.Store(defaultXMLPathContentTypes, MacintoshCyrillicCharset)
-	assert.EqualError(t, f.AddShape("Sheet1", "B30", &Shape{Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}), "XML syntax error on line 1: invalid UTF-8")
+	assert.EqualError(t, f.AddShape("Sheet1", &Shape{Cell: "B30", Type: "rect", Paragraph: []RichTextRun{{Text: "Rectangle"}, {}}}), "XML syntax error on line 1: invalid UTF-8")
 }
 
 func TestAddDrawingShape(t *testing.T) {