| /* |
| * ==================================================================== |
| * 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); |
| } |