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

   1 /* ====================================================================
   2    Licensed to the Apache Software Foundation (ASF) under one or more
   3    contributor license agreements.  See the NOTICE file distributed with
   4    this work for additional information regarding copyright ownership.
   5    The ASF licenses this file to You under the Apache License, Version 2.0
   6    (the "License"); you may not use this file except in compliance with
   7    the License.  You may obtain a copy of the License at
   8
   9        http://www.apache.org/licenses/LICENSE-2.0
  10
  11    Unless required by applicable law or agreed to in writing, software
  12    distributed under the License is distributed on an "AS IS" BASIS,
  13    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14    See the License for the specific language governing permissions and
  15    limitations under the License.
  16 ==================================================================== */
  17 package org.apache.poi.hssf.usermodel;
  18
  19 import org.apache.poi.hssf.record.CFHeaderRecord;
  20 import org.apache.poi.hssf.record.CFRuleRecord;
  21 import org.apache.poi.hssf.record.aggregates.CFRecordsAggregate;
  22 import org.apache.poi.hssf.record.cf.CellRange;
  23 import org.apache.poi.hssf.util.Region;
  24
  25 /**
  26  * HSSFConditionalFormatting class encapsulates all settings of Conditional Formatting.
  27  *
  28  * The class can be used
  29  *
  30  * <UL>
  31  * <LI>
  32  * to make a copy HSSFConditionalFormatting settings.
  33  * </LI>
  34  *
  35  *
  36  * For example:
  37  * <PRE>
  38  * HSSFConditionalFormatting cf = sheet.getConditionalFormattingAt(index);
  39  * newSheet.addConditionalFormatting(cf);
  40  * </PRE>
  41  *
  42  *  <LI>
  43  *  or to modify existing Conditional Formatting settings (formatting regions and/or rules).
  44  *  </LI>
  45  *  </UL>
  46  *
  47  * Use {@link HSSFSheet#getConditionalFormattingAt(int)} to get access to an instance of this class.
  48  * <P>
  49  * To create a new Conditional Formatting set use the following approach:
  50  *
  51  * <PRE>
  52  *
  53  * // Define a Conditional Formatting rule, which triggers formatting
  54  * // when cell's value is greater or equal than 100.0 and
  55  * // applies patternFormatting defined below.
  56  * HSSFConditionalFormattingRule rule = sheet.createConditionalFormattingRule(
  57  *     ComparisonOperator.GE,
  58  *     "100.0", // 1st formula
  59  *     null     // 2nd formula is not used for comparison operator GE
  60  * );
  61  *
  62  * // Create pattern with red background
  63  * HSSFPatternFormatting patternFmt = rule.cretePatternFormatting();
  64  * patternFormatting.setFillBackgroundColor(HSSFColor.RED.index);
  65  *
  66  * // Define a region containing first column
  67  * Region [] regions =
  68  * {
  69  *     new Region(1,(short)1,-1,(short)1)
  70  * };
  71  *
  72  * // Apply Conditional Formatting rule defined above to the regions
  73  * sheet.addConditionalFormatting(regions, rule);
  74  * </PRE>
  75  *
  76  * @author Dmitriy Kumshayev
  77  */
  78 public final class HSSFConditionalFormatting
  79 {
  80         private final HSSFWorkbook _workbook;
  81         private final CFRecordsAggregate cfAggregate;
  82
  83         HSSFConditionalFormatting(HSSFWorkbook workbook, CFRecordsAggregate cfAggregate)
  84         {
  85                 if(workbook == null) {
  86                         throw new IllegalArgumentException("workbook must not be null");
  87                 }
  88                 if(cfAggregate == null) {
  89                         throw new IllegalArgumentException("cfAggregate must not be null");
  90                 }
  91                 _workbook = workbook;
  92                 this.cfAggregate = cfAggregate;
  93         }
  94         CFRecordsAggregate getCFRecordsAggregate() {
  95                 return cfAggregate;
  96         }
  97
  98         /**
  99          * @return array of <tt>Region</tt>s. never <code>null</code>
 100          */
 101         public Region[] getFormattingRegions()
 102         {
 103                 CFHeaderRecord cfh = cfAggregate.getHeader();
 104                 CellRange[] cellRanges = cfh.getCellRanges();
 105                 return CellRange.convertCellRangesToRegions(cellRanges);
 106         }
 107
 108         /**
 109          * Replaces an existing Conditional Formatting rule at position idx.
 110          * Excel allows to create up to 3 Conditional Formatting rules.
 111          * This method can be useful to modify existing  Conditional Formatting rules.
 112          *
 113          * @param idx position of the rule. Should be between 0 and 2.
 114          * @param cfRule - Conditional Formatting rule
 115          */
 116         public void setRule(int idx, HSSFConditionalFormattingRule cfRule)
 117         {
 118                 cfAggregate.setRule(idx, cfRule.getCfRuleRecord());
 119         }
 120
 121         /**
 122          * add a Conditional Formatting rule.
 123          * Excel allows to create up to 3 Conditional Formatting rules.
 124          * @param cfRule - Conditional Formatting rule
 125          */
 126         public void addRule(HSSFConditionalFormattingRule cfRule)
 127         {
 128                 cfAggregate.addRule(cfRule.getCfRuleRecord());
 129         }
 130
 131         /**
 132          * @return the Conditional Formatting rule at position idx.
 133          */
 134         public HSSFConditionalFormattingRule getRule(int idx)
 135         {
 136                 CFRuleRecord ruleRecord = cfAggregate.getRule(idx);
 137                 return new HSSFConditionalFormattingRule(_workbook, ruleRecord);
 138         }
 139
 140         /**
 141          * @return number of Conditional Formatting rules.
 142          */
 143         public int getNumberOfRules()
 144         {
 145                 return cfAggregate.getNumberOfRules();
 146         }
 147
 148         public String toString()
 149         {
 150                 return cfAggregate.toString();
 151         }
 152 }