/*
* ====================================================================
* 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;
import org.apache.poi.ss.usermodel.IconMultiStateFormatting.IconSet;
import org.apache.poi.ss.util.CellRangeAddress;
/**
* The 'Conditional Formatting' facet of <tt>Sheet</tt>
*
* @since 3.8
*/
public interface SheetConditionalFormatting {
/**
* Add a new Conditional Formatting to the sheet.
*
* @param regions - list of rectangular regions to apply conditional formatting rules
* @param rule - the rule to apply
*
* @return index of the newly created Conditional Formatting object
*/
int addConditionalFormatting(CellRangeAddress[] regions,
ConditionalFormattingRule rule);
/**
* Add a new Conditional Formatting consisting of two rules.
*
* @param regions - list of rectangular regions to apply conditional formatting rules
* @param rule1 - the first rule
* @param rule2 - the second rule
*
* @return index of the newly created Conditional Formatting object
*/
int addConditionalFormatting(CellRangeAddress[] regions,
ConditionalFormattingRule rule1,
ConditionalFormattingRule rule2);
/**
* Add a new Conditional Formatting set to the sheet.
*
* @param regions - list of rectangular regions to apply conditional formatting rules
* @param cfRules - set of up to conditional formatting rules (max 3 for Excel pre-2007)
*
* @return index of the newly created Conditional Formatting object
*/
int addConditionalFormatting(CellRangeAddress[] regions, ConditionalFormattingRule[] cfRules);
/**
* Adds a copy of a ConditionalFormatting object to the sheet
* <p>
* This method could be used to copy ConditionalFormatting object
* from one sheet to another. For example:
* </p>
* <pre>
* ConditionalFormatting cf = sheet.getConditionalFormattingAt(index);
* newSheet.addConditionalFormatting(cf);
* </pre>
*
* @param cf the Conditional Formatting to clone
* @return index of the new Conditional Formatting object
*/
int addConditionalFormatting(ConditionalFormatting cf);
/**
* A factory method allowing to create a conditional formatting rule
* with a cell comparison operator
* <p>
* The created conditional formatting rule compares a cell value
* to a formula calculated result, using the specified operator.
* The type of the created condition is {@link ConditionType#CELL_VALUE_IS}
* </p>
*
* @param comparisonOperation - MUST be a constant value from
* <tt>{@link ComparisonOperator}</tt>: <p>
* <ul>
* <li>BETWEEN</li>
* <li>NOT_BETWEEN</li>
* <li>EQUAL</li>
* <li>NOT_EQUAL</li>
* <li>GT</li>
* <li>LT</li>
* <li>GE</li>
* <li>LE</li>
* </ul>
* </p>
* @param formula1 - formula for the valued, compared with the cell
* @param formula2 - second formula (only used with
* {@link ComparisonOperator#BETWEEN}) and {@link ComparisonOperator#NOT_BETWEEN} operations)
*/
ConditionalFormattingRule createConditionalFormattingRule(
byte comparisonOperation,
String formula1,
String formula2);
/**
* Create a conditional formatting rule that compares a cell value
* to a formula calculated result, using an operator *
* <p>
* The type of the created condition is {@link ConditionType#CELL_VALUE_IS}
* </p>
*
* @param comparisonOperation MUST be a constant value from
* <tt>{@link ComparisonOperator}</tt> except BETWEEN and NOT_BETWEEN
*
* @param formula the formula to determine if the conditional formatting is applied
*/
ConditionalFormattingRule createConditionalFormattingRule(
byte comparisonOperation,
String formula);
/**
* Create a conditional formatting rule based on a Boolean formula.
* When the formula result is true, the cell is highlighted.
*
* <p>
* The type of the created format condition is {@link ConditionType#FORMULA}
* </p>
* @param formula the formula to evaluate. MUST be a Boolean function.
*/
ConditionalFormattingRule createConditionalFormattingRule(String formula);
/**
* Create a Databar conditional formatting rule.
* <p>The thresholds and colour for it will be created, but will be
* empty and require configuring with
* {@link ConditionalFormattingRule#getDataBarFormatting()}
* then
* {@link DataBarFormatting#getMinThreshold()}
* and
* {@link DataBarFormatting#getMaxThreshold()}
*/
ConditionalFormattingRule createConditionalFormattingRule(ExtendedColor color);
/**
* Create an Icon Set / Multi-State conditional formatting rule.
* <p>The thresholds for it will be created, but will be empty
* and require configuring with
* {@link ConditionalFormattingRule#getMultiStateFormatting()}
* then
* {@link IconMultiStateFormatting#getThresholds()}
*/
ConditionalFormattingRule createConditionalFormattingRule(IconSet iconSet);
/**
* Create a Color Scale / Color Gradient conditional formatting rule.
* <p>The thresholds and colours for it will be created, but will be
* empty and require configuring with
* {@link ConditionalFormattingRule#getColorScaleFormatting()}
* then
* {@link ColorScaleFormatting#getThresholds()}
* and
* {@link ColorScaleFormatting#getColors()}
*/
ConditionalFormattingRule createConditionalFormattingColorScaleRule();
/**
* Gets Conditional Formatting object at a particular index
*
* @param index 0-based index of the Conditional Formatting object to fetch
* @return Conditional Formatting object or <code>null</code> if not found
* @throws IllegalArgumentException if the index is outside of the allowable range (0 ... numberOfFormats-1)
*/
ConditionalFormatting getConditionalFormattingAt(int index);
/**
*
* @return the number of conditional formats in this sheet
*/
int getNumConditionalFormattings();
/**
* Removes a Conditional Formatting object by index
*
* @param index 0-based index of the Conditional Formatting object to remove
* @throws IllegalArgumentException if the index is outside of the allowable range (0 ... numberOfFormats-1)
*/
void removeConditionalFormatting(int index);
}