bug 60605: convert Workbook.SHEET_STATE_* to SheetVisibility enum

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1779558 13f79535-47bb-0310-9956-ffa450edef68

Author: onealj

src/java/org/apache/poi/hssf/model/InternalWorkbook.java

@@ -105,6 +105,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import org.apache.poi.ss.formula.ptg.Ref3DPtg;
 import org.apache.poi.ss.formula.udf.UDFFinder;
 import org.apache.poi.ss.usermodel.BuiltinFormats;
+import org.apache.poi.ss.usermodel.SheetVisibility;
 import org.apache.poi.ss.usermodel.Workbook;
 import org.apache.poi.util.Internal;
 import org.apache.poi.util.LocaleUtil;
@@ -715,6 +716,27 @@ public boolean isSheetHidden(int sheetnum) {
     public boolean isSheetVeryHidden(int sheetnum) {
         return getBoundSheetRec(sheetnum).isVeryHidden();
     }
+    
+    /**
+     * Gets the hidden flag for a given sheet.
+     * Note that a sheet could instead be
+     *  set to be very hidden, which is different
+     *  ({@link #isSheetVeryHidden(int)})
+     *
+     * @param sheetnum the sheet number (0 based)
+     * @return True if sheet is hidden
+     * @since 3.16 beta 2
+     */
+    public SheetVisibility getSheetVisibility(int sheetnum) {
+        final BoundSheetRecord bsr = getBoundSheetRec(sheetnum);
+        if (bsr.isVeryHidden()) {
+            return SheetVisibility.VERY_HIDDEN;
+        }
+        if (bsr.isHidden()) {
+            return SheetVisibility.HIDDEN;
+        }
+        return SheetVisibility.VISIBLE;
+    }
 
     /**
      * Hide or unhide a sheet
@@ -723,32 +745,20 @@ public boolean isSheetVeryHidden(int sheetnum) {
      * @param hidden True to mark the sheet as hidden, false otherwise
      */
     public void setSheetHidden(int sheetnum, boolean hidden) {
-        getBoundSheetRec(sheetnum).setHidden(hidden);
+        setSheetHidden(sheetnum, hidden ? SheetVisibility.HIDDEN : SheetVisibility.VISIBLE);
     }
 
     /**
      * Hide or unhide a sheet.
-     *  0 = not hidden
-     *  1 = hidden
-     *  2 = very hidden.
      *
-     * @param sheetnum The sheet number
-     * @param hidden 0 for not hidden, 1 for hidden, 2 for very hidden
+     * @param sheetnum   The sheet number
+     * @param visibility the sheet visibility to set (visible, hidden, very hidden)
+     * @since 3.16 beta 2
      */
-    public void setSheetHidden(int sheetnum, int hidden) {
+    public void setSheetHidden(int sheetnum, SheetVisibility visibility) {
         BoundSheetRecord bsr = getBoundSheetRec(sheetnum);
-        boolean h = false;
-        boolean vh = false;
-        if(hidden == 0) {
-        } else if(hidden == 1) {
-            h = true;
-        } else if(hidden == 2) {
-            vh = true;
-        } else {
-            throw new IllegalArgumentException("Invalid hidden flag " + hidden + " given, must be 0, 1 or 2");
-        }
-        bsr.setHidden(h);
-        bsr.setVeryHidden(vh);
+        bsr.setHidden(visibility == SheetVisibility.HIDDEN);
+        bsr.setVeryHidden(visibility == SheetVisibility.VERY_HIDDEN);
     }
 
 

src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java

@@ -100,6 +100,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import org.apache.poi.ss.usermodel.Name;
 import org.apache.poi.ss.usermodel.Row.MissingCellPolicy;
 import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.ss.usermodel.SheetVisibility;
 import org.apache.poi.ss.usermodel.Workbook;
 import org.apache.poi.ss.util.WorkbookUtil;
 import org.apache.poi.util.Configurator;
@@ -188,7 +189,7 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      */
     private MissingCellPolicy missingCellPolicy = MissingCellPolicy.RETURN_NULL_AND_BLANK;
 
-    private static POILogger log = POILogFactory.getLogger(HSSFWorkbook.class);
+    private static final POILogger log = POILogFactory.getLogger(HSSFWorkbook.class);
 
     /**
      * The locator of user-defined functions.
@@ -748,19 +749,46 @@ public boolean isSheetVeryHidden(int sheetIx) {
         validateSheetIndex(sheetIx);
         return workbook.isSheetVeryHidden(sheetIx);
     }
-
+    
+    @Override
+    public SheetVisibility getSheetVisibility(int sheetIx) {
+        return workbook.getSheetVisibility(sheetIx);
+    }
 
     @Override
     public void setSheetHidden(int sheetIx, boolean hidden) {
-        validateSheetIndex(sheetIx);
-        workbook.setSheetHidden(sheetIx, hidden);
+        setSheetVisibility(sheetIx, hidden ? SheetVisibility.HIDDEN : SheetVisibility.VISIBLE);
     }
 
+    @Removal(version="3.18")
+    @Deprecated
     @Override
     public void setSheetHidden(int sheetIx, int hidden) {
+        switch (hidden) {
+            case Workbook.SHEET_STATE_VISIBLE:
+                setSheetVisibility(sheetIx, SheetVisibility.VISIBLE);
+                break;
+            case Workbook.SHEET_STATE_HIDDEN:
+                setSheetVisibility(sheetIx, SheetVisibility.HIDDEN);
+                break;
+            case Workbook.SHEET_STATE_VERY_HIDDEN:
+                setSheetVisibility(sheetIx, SheetVisibility.VERY_HIDDEN);
+                break;
+            default:
+                throw new IllegalArgumentException("Invalid sheet state : " + hidden + "\n" +
+                        "Sheet state must beone of the Workbook.SHEET_STATE_* constants");
+        }
+    }
+    
+    @Override
+    public void setSheetVisibility(int sheetIx, SheetVisibility visibility) {
         validateSheetIndex(sheetIx);
-        WorkbookUtil.validateSheetState(hidden);
-        workbook.setSheetHidden(sheetIx, hidden);
+        
+        /*if (visibility != SheetVisibility.VISIBLE && sheetIx == getActiveSheetIndex()) {
+            throw new IllegalStateException("Cannot hide the active sheet. Change active sheet before hiding.");
+        }*/
+        
+        workbook.setSheetHidden(sheetIx, visibility);
     }
 
     /** Returns the index of the sheet by his name

src/java/org/apache/poi/ss/usermodel/SheetVisibility.java

@@ -0,0 +1,46 @@
+/* ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+
+package org.apache.poi.ss.usermodel;
+
+/**
+ * Specifies sheet visibility
+ *
+ * @see Workbook#getSheetVisibility(int)
+ * @see Workbook#setSheetVisibility(int, SheetVisibility)
+ */
+public enum SheetVisibility {
+
+    /**
+     * Indicates the sheet is visible.
+     */
+    VISIBLE,
+    /**
+     * Indicates the book window is hidden, but can be shown by the user via the user interface.
+     */
+    HIDDEN,
+
+    /**
+     * Indicates the sheet is hidden and cannot be shown in the user interface (UI).
+     *
+     * <p>
+     * In Excel this state is only available programmatically in VBA:
+     * <code>ThisWorkbook.Sheets("MySheetName").Visible = xlSheetVeryHidden </code>
+     * </p>
+     */
+    VERY_HIDDEN;
+}

src/java/org/apache/poi/ss/usermodel/Workbook.java

@@ -26,6 +26,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import org.apache.poi.ss.SpreadsheetVersion;
 import org.apache.poi.ss.formula.udf.UDFFinder;
 import org.apache.poi.ss.usermodel.Row.MissingCellPolicy;
+import org.apache.poi.util.Removal;
 
 /**
  * High level representation of a Excel workbook.  This is the first object most users
@@ -57,14 +58,20 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      * Indicates the sheet is visible.
      *
      * @see #setSheetHidden(int, int)
+     * @deprecated POI 3.16 beta 2. Use {@link SheetVisibility#VISIBLE} instead.
      */
+    @Deprecated
+    @Removal(version="3.18")
     int SHEET_STATE_VISIBLE = 0;
 
     /**
      * Indicates the book window is hidden, but can be shown by the user via the user interface.
      *
      * @see #setSheetHidden(int, int)
+     * @deprecated POI 3.16 beta 2. Use {@link SheetVisibility#HIDDEN} instead.
      */
+    @Deprecated
+    @Removal(version="3.18")
     int SHEET_STATE_HIDDEN = 1;
 
     /**
@@ -76,7 +83,10 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      * </p>
      *
      * @see #setSheetHidden(int, int)
+     * @deprecated POI 3.16 beta 2. Use {@link SheetVisibility#VERY_HIDDEN} instead.
      */
+    @Deprecated
+    @Removal(version="3.18")
     int SHEET_STATE_VERY_HIDDEN = 2;
 
     /**
@@ -550,6 +560,7 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      * </p>
      * @param sheetIx Number
      * @return <code>true</code> if sheet is hidden
+     * @see #getSheetVisibility(int)
      */
     boolean isSheetHidden(int sheetIx);
 
@@ -561,6 +572,7 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      * </p>
      * @param sheetIx sheet index to check
      * @return <code>true</code> if sheet is very hidden
+     * @see #getSheetVisibility(int)
      */
     boolean isSheetVeryHidden(int sheetIx);
 
@@ -572,6 +584,7 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      *
      * @param sheetIx the sheet index (0-based)
      * @param hidden True to mark the sheet as hidden, false otherwise
+     * @see #setSheetVisibility(int, SheetVisibility)
      */
     void setSheetHidden(int sheetIx, boolean hidden);
 
@@ -593,8 +606,31 @@ public interface Workbook extends Closeable, Iterable<Sheet> {
      *        <code>Workbook.SHEET_STATE_HIDDEN</code>, or
      *        <code>Workbook.SHEET_STATE_VERY_HIDDEN</code>.
      * @throws IllegalArgumentException if the supplied sheet index or state is invalid
+     * @deprecated POI 3.16 beta 2. Use {@link #setSheetVisibility(int, SheetVisibility)} instead.
      */
+    @Removal(version="3.18")
     void setSheetHidden(int sheetIx, int hidden);
+    
+    /**
+     * Get the visibility (visible, hidden, very hidden) of a sheet in this workbook
+     *
+     * @param sheetIx  the index of the sheet
+     * @return the sheet visibility
+     * @since POI 3.16 beta 2
+     */
+    SheetVisibility getSheetVisibility(int sheetIx);
+
+    /**
+     * Hide or unhide a sheet.
+     *
+     * Please note that the sheet currently set as active sheet (sheet 0 in a newly 
+     * created workbook or the one set via setActiveSheet()) cannot be hidden.
+     *  
+     * @param sheetIx     the sheet index (0-based)
+     * @param visibility  the sheet visibility to set
+     * @since POI 3.16 beta 2
+     */
+    void setSheetVisibility(int sheetIx, SheetVisibility visibility);
 
     /**
      * Register a new toolpack in this workbook.

src/java/org/apache/poi/ss/util/WorkbookUtil.java

@@ -17,7 +17,10 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 
 package org.apache.poi.ss.util;
 
+import org.apache.poi.ss.usermodel.SheetVisibility;
 import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.util.Internal;
+import org.apache.poi.util.Removal;
 
 
 /**
@@ -169,14 +172,46 @@ public static void validateSheetName(String sheetName) {
      *      {@link Workbook#SHEET_STATE_VISIBLE},
      *      {@link Workbook#SHEET_STATE_HIDDEN} or
      *      {@link Workbook#SHEET_STATE_VERY_HIDDEN}
+     * @deprecated POI 3.16 beta 2. Use {@link org.apache.poi.ss.usermodel.SheetVisibility} instead.
      */
+    @Removal(version="3.18")
+    @Deprecated
     public static void validateSheetState(int state) {
         switch(state){
             case Workbook.SHEET_STATE_VISIBLE: break;
             case Workbook.SHEET_STATE_HIDDEN: break;
             case Workbook.SHEET_STATE_VERY_HIDDEN: break;
-            default: throw new IllegalArgumentException("Ivalid sheet state : " + state + "\n" +
+            default: throw new IllegalArgumentException("Invalid sheet state : " + state + "\n" +
                             "Sheet state must beone of the Workbook.SHEET_STATE_* constants");
         }
-    }    
+    }
+    
+    @Internal(since="3.16 beta 2")
+    public static int getNextActiveSheetDueToSheetHiding(Workbook wb, int sheetIx) {
+        if (sheetIx == wb.getActiveSheetIndex()) {
+            // activate next sheet
+            // if last sheet in workbook, the previous visible sheet should be activated
+            final int count = wb.getNumberOfSheets();
+            for (int i=sheetIx+1; i < count; i++) {
+                // get the next visible sheet in this workbook
+                if (SheetVisibility.VISIBLE == wb.getSheetVisibility(i)) {
+                    return i;
+                }
+            }
+            
+            // if there are no sheets to the right or all sheets to the right are hidden, activate a sheet to the left
+            for (int i=sheetIx-1; i < count; i--) {
+                if (SheetVisibility.VISIBLE == wb.getSheetVisibility(i)) {
+                    return i;
+                }
+            }
+            
+            // there are no other visible sheets in this workbook
+            return -1;
+            //throw new IllegalStateException("Cannot hide sheet " + sheetIx + ". Workbook must contain at least 1 other visible sheet.");
+        }
+        else {
+            return sheetIx;
+        }
+    }
 }