platform/lang-api/src/com/intellij/formatting/Alignment.java

/*
 * Copyright 2000-2009 JetBrains s.r.o.
 *
 * Licensed 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 com.intellij.formatting;

import org.jetbrains.annotations.NotNull;

/**
 * The alignment setting for a formatting model block. Blocks which return the same
 * alignment object instance from the <code>getAlignment</code> method
 * are aligned with each other.
 *
 * @see com.intellij.formatting.Block#getAlignment()
 * @see com.intellij.formatting.ChildAttributes#getAlignment()
 */

public abstract class Alignment {

  public enum Anchor { LEFT, RIGHT }

  private static AlignmentFactory myFactory;

  static void setFactory(AlignmentFactory factory) {
    myFactory = factory;
  }

  /**
   * Shorthand for calling {@link #createAlignment(boolean)} with <code>'false'</code>.
   *
   * @return      alignment object with default settings
   */
  public static Alignment createAlignment() {
    return createAlignment(false, Anchor.LEFT);
  }

  /**
   * Delegates the processing to {@link #createAlignment(boolean, Anchor)} with given <code>'allow backward shift'</code> value
   * and {@link Anchor#LEFT}.
   *
   * @param allowBackwardShift    flag that specifies if former aligned block may be shifted to right in order to align to subsequent
   *                              aligned block
   * @return                      alignment object with the given <code>'allow backward shift'</code> setting
   */
  public static Alignment createAlignment(boolean allowBackwardShift) {
    return createAlignment(allowBackwardShift, Anchor.LEFT);
  }

  /**
   * Allows to create {@link Alignment} object with the given settings.
   * <p/>
   * <pre>
   * <ul>
   *   <li>
   *      <b>Allow backward shift</b>
   *      <p/>
   *      Specifies if former aligned element may be shifted to right in order to align to subsequent element.
   *      <p/>
   *      Consider the following example:
   *      <p/>
   *      <pre>
   *          int start  = 1;
   *          int finish = 2;
   *      </pre>
   *      <p/>
   *      Here <code>'='</code> block of <code>'int start  = 1'</code> statement is shifted one symbol right in order to align
   *      to the <code>'='</code> block of <code>'int finish  = 1'</code> statement.
   *   </li>
   *   <li>
   *     <b>Anchor</b>
   *     Identifies how code blocks should be aligned.
   *     <pre>
   *     <ul>
   *         <li>
   *           <b>LEFT:</b>
   *           <p/>
   *           <pre>
   *             int  start  = 1;
   *             long finish = 2;
   *           </pre>
   *         </li>
   *         <li>
   *           <b>RIGHT:</b>
   *           <p/>
   *           <pre>
   *              int  start = 1;
   *             long finish = 2;
   *           </pre>
   *         </li>
   *     </ul>
   *     </pre>
   *   </li>
   * </ul>
   * </pre>
   *
   * @param allowBackwardShift    flag that specifies if former aligned block may be shifted to right in order to align to subsequent
   *                              aligned block
   * @param anchor                alignment anchor
   * @return                      alignment object with the given <code>'allow backward shift'</code> setting
   */
  public static Alignment createAlignment(boolean allowBackwardShift, @NotNull Anchor anchor) {
    return myFactory.createAlignment(allowBackwardShift, anchor);
  }
  
  /**
   * Allows to create alignment with the following feature - aligned blocks are aligned to block with the current alignment if the one
   * if found; block with the given <code>'base'</code> alignment is checked otherwise.
   * <p/>
   * Example:
   * <p/>
   * <pre>
   *     int i = a ? x
   *               : y;
   * </pre>
   * <p/>
   * Here <code>':'</code> is aligned to <code>'?'</code> and alignment of <code>'a'</code> is a <code>'base alignment'</code>
   * of <code>'?'</code> alignment. I.e. the thing is that <code>':'</code> is not aligned to <code>'a'</code>.
   * <p/>
   * However, we can change example as follows:
   * <p/>
   * <pre>
   *     int i = a
   *             ? x : y;
   * </pre>
   * <p/>
   * Here <code>'?'</code> is aligned to <code>'a'</code> because the later is set as a <code>'base alignment'</code> for <code>'?'</code>.
   * Note that we can't just define the same {@link #createAlignment() simple alignment} for all blocks <code>'a'</code>,
   * <code>'?'</code> and <code>':'</code> because it would produce formatting like the one below:
   * <p/>
   * <pre>
   *     int i = a ? x
   *             : y;
   * </pre>
   *
   * @param base    base alignment to use within returned alignment object
   * @return        alignment object with the given alignment defined as a <code>'base alignment'</code>
   */
  public static Alignment createChildAlignment(final Alignment base) {
    return myFactory.createChildAlignment(base);
  }
}