Add new function: AddSlicer

- Update unit test and fix AddShape test case failed

Author: xuri

Excelize.Tests/UnitTest.cs

@@ -550,7 +550,9 @@ public void TestAddShape()
                 );
             })
         );
-        RuntimeError err = Assert.Throws<RuntimeError>(() => f.AddShape("SheetN", new Shape { }));
+        RuntimeError err = Assert.Throws<RuntimeError>(() =>
+            f.AddShape("SheetN", new Shape { Cell = "G6", Type = "rect" })
+        );
         Assert.Equal("sheet SheetN does not exist", err.Message);
         Assert.Null(
             Record.Exception(() =>
@@ -710,6 +712,7 @@ public void TestPivotTable()
                     {
                         DataRange = "Sheet1!A1:E31",
                         PivotTableRange = "Sheet1!G2:M34",
+                        Name = "PivotTable1",
                         Rows = new PivotTableField[]
                         {
                             new() { Data = "Month", DefaultSubtotal = true },
@@ -737,6 +740,17 @@ public void TestPivotTable()
                         ShowLastColumn = true,
                     }
                 );
+                f.AddSlicer(
+                    "Sheet1",
+                    new SlicerOptions
+                    {
+                        Name = "Month",
+                        Cell = "O2",
+                        TableSheet = "Sheet1",
+                        TableName = "PivotTable1",
+                        Caption = "Month",
+                    }
+                );
             })
         );
         RuntimeError err = Assert.Throws<RuntimeError>(() =>
@@ -746,6 +760,22 @@ public void TestPivotTable()
             "parameter 'PivotTableRange' parsing error: parameter is required",
             err.Message
         );
+
+        err = Assert.Throws<RuntimeError>(() =>
+            f.AddSlicer(
+                "SheetN",
+                new SlicerOptions
+                {
+                    Name = "Year",
+                    Cell = "S2",
+                    TableSheet = "Sheet1",
+                    TableName = "PivotTable1",
+                    Caption = "Year",
+                }
+            )
+        );
+        Assert.Equal("sheet SheetN does not exist", err.Message);
+
         Assert.Null(
             Record.Exception(() =>
             {
@@ -755,6 +785,16 @@ public void TestPivotTable()
         Assert.Empty(f.Close());
     }
 
+    [Fact]
+    public void TestAddSlicer()
+    {
+        File f = Excelize.NewFile();
+        RuntimeError err = Assert.Throws<RuntimeError>(() =>
+            f.AddSlicer("Sheet1", new SlicerOptions { })
+        );
+        Assert.Equal("parameter is invalid", err.Message);
+    }
+
     [StructLayout(LayoutKind.Sequential)]
     public unsafe struct C1
     {

Excelize/Excelize.cs

@@ -142,6 +142,13 @@ internal static extern IntPtr AddShape(
             ref TypesC.Shape opts
         );
 
+        [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)]
+        internal static extern IntPtr AddSlicer(
+            long fileIdx,
+            [MarshalAs(UnmanagedType.LPUTF8Str)] string sheet,
+            ref TypesC.SlicerOptions opts
+        );
+
         [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)]
         internal static extern IntPtr AddVBAProject(long fileIdx, byte[] b, int bLen);
 
@@ -1963,6 +1970,41 @@ public void AddShape(string sheet, Shape options)
                 throw new RuntimeError(err);
         }
 
+        /// <summary>
+        /// AddSlicer function inserts a slicer by giving the worksheet name and
+        /// slicer settings.
+        /// <example>
+        /// For example, insert a slicer on the <c>Sheet1!E1</c> with field
+        /// <c>Column1</c> for the table named <c>Table1</c>:
+        /// <code>
+        /// f.AddSlicer(
+        ///     "Sheet1",
+        ///     new SlicerOptions
+        ///     {
+        ///         Name = "Column1",
+        ///         Cell = "E1",
+        ///         TableSheet = "Sheet1",
+        ///         TableName = "Table1",
+        ///         Caption = "Column1",
+        ///         Width = 200,
+        ///         Height = 200,
+        ///     }
+        /// );
+        /// </code>
+        /// </example>
+        /// </summary>
+        /// <param name="sheet">The worksheet name</param>
+        /// <param name="options">The slicer options</param>
+        /// <exception cref="RuntimeError">Return None if no error occurred,
+        /// otherwise raise a RuntimeError with the message.</exception>
+        public void AddSlicer(string sheet, SlicerOptions options)
+        {
+            var opts = (TypesC.SlicerOptions)Lib.CsToC(options, new TypesC.SlicerOptions());
+            string err = Marshal.PtrToStringUTF8(Lib.AddSlicer(FileIdx, sheet, ref opts));
+            if (!string.IsNullOrEmpty(err))
+                throw new RuntimeError(err);
+        }
+
         /// <summary>
         /// Add vbaProject.bin file which contains functions and/or macros. The
         /// file extension should be XLSM or XLTM.

Excelize/TypesC.cs

@@ -533,6 +533,24 @@ public unsafe struct SheetPropsOptions
         public bool* ThickBottom;
     }
 
+    [StructLayout(LayoutKind.Sequential)]
+    public unsafe struct SlicerOptions
+    {
+        public sbyte* Name;
+        public sbyte* Cell;
+        public sbyte* TableSheet;
+        public sbyte* TableName;
+        public sbyte* Caption;
+        public sbyte* Macro;
+        public uint Width;
+        public uint Height;
+        public bool* DisplayHeader;
+
+        [MarshalAs(UnmanagedType.I1)]
+        public bool ItemDesc;
+        public GraphicOptions Format;
+    }
+
     [StructLayout(LayoutKind.Sequential)]
     public unsafe struct StringErrorResult
     {

Excelize/TypesCs.cs

@@ -683,6 +683,51 @@ public struct SheetPropsOptions
         public bool? ThickBottom;
     }
 
+    /// <summary>
+    /// Represents the settings of the slicer.
+    /// </summary>
+    /// <remarks>
+    /// <para><b>Name</b> specifies the slicer name and should be an existing
+    /// field name of the given table or pivot table. This setting is
+    /// required.</para>
+    /// <para><b>Cell</b> specifies the top-left cell coordinates for inserting
+    /// the slicer. This setting is required.</para>
+    /// <para><b>TableSheet</b> specifies the worksheet name of the table or
+    /// pivot table. This setting is required.</para>
+    /// <para><b>TableName</b> specifies the name of the table or pivot table.
+    /// This setting is required.</para>
+    /// <para><b>Caption</b> specifies the caption of the slicer. This setting
+    /// is optional.</para>
+    /// <para><b>Macro</b> specifies the macro to assign to the slicer. The
+    /// workbook extension should be XLSM or XLTM.</para>
+    /// <para><b>Width</b> specifies the width of the slicer. This setting is
+    /// optional.</para>
+    /// <para><b>Height</b> specifies the height of the slicer. This setting is
+    /// optional.</para>
+    /// <para><b>DisplayHeader</b> specifies whether the slicer header is
+    /// displayed. This setting is optional; the default is to display
+    /// it.</para>
+    /// <para><b>ItemDesc</b> specifies whether to sort items in descending
+    /// (Z-A) order. This setting is optional; the default is false
+    /// (ascending).</para>
+    /// <para><b>Format</b> specifies the format of the slicer. This setting is
+    /// optional.</para>
+    /// </remarks>
+    public struct SlicerOptions
+    {
+        public string Name;
+        public string Cell;
+        public string TableSheet;
+        public string TableName;
+        public string Caption;
+        public string Macro;
+        public uint Width;
+        public uint Height;
+        public bool? DisplayHeader;
+        public bool ItemDesc;
+        public GraphicOptions Format;
+    }
+
     public struct Row
     {
         public string[]? Cell;