001    /*
002     * Created on Mar 4, 2008
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     * 
007     * http://www.apache.org/licenses/LICENSE-2.0
008     * 
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     * 
014     * Copyright @2008-2010 the original author or authors.
015     */
016    package org.fest.swing.core;
017    
018    import java.awt.Component;
019    import java.awt.Container;
020    import java.io.PrintStream;
021    
022    import org.fest.swing.format.Formatting;
023    
024    /**
025     * Understands printing the <code>String</code> representation of <code>{@link java.awt.Component}</code>s to
026     * facilitate debugging.
027     * 
028     * @author Alex Ruiz
029     */
030    public interface ComponentPrinter {
031    
032      /**
033       * Prints all the components in the hierarchy.
034       * @param out the output stream where to print the components to.
035       * @see Formatting#format(Component)
036       * @throws NullPointerException if the output stream is <code>null</code>.
037       */
038      void printComponents(PrintStream out);
039    
040      /**
041       * Prints all the components in the hierarchy under the given root.
042       * @param out the output stream where to print the components to.
043       * @param root the root used as the starting point of the search.
044       * @see Formatting#format(Component)
045       * @throws NullPointerException if the output stream is <code>null</code>.
046       */
047      void printComponents(PrintStream out, Container root);
048    
049      /**
050       * Prints only the components of the given type in the hierarchy.
051       * @param out the output stream where to print the components to.
052       * @param type the type of components to print.
053       * @see Formatting#format(Component)
054       * @throws NullPointerException if the output stream is <code>null</code>.
055       * @throws NullPointerException if <code>type</code> is <code>null</code>.
056       */
057      void printComponents(PrintStream out, Class<? extends Component> type);
058    
059      /**
060       * Prints all the components of the given type in the hierarchy under the given root.
061       * @param out the output stream where to print the components to.
062       * @param type the type of components to print.
063       * @param root the root used as the starting point of the search.
064       * @see Formatting#format(Component)
065       * @throws NullPointerException if the output stream is <code>null</code>.
066       * @throws NullPointerException if <code>type</code> is <code>null</code>.
067       */
068      void printComponents(PrintStream out, Class<? extends Component> type, Container root);
069    
070      /**
071       * Prints only the components that match the given search criteria in the hierarchy.
072       * @param out the output stream where to print the components to.
073       * @param matcher specifies the search criteria to use filter the components to print.
074       * @see Formatting#format(Component)
075       * @throws NullPointerException if the output stream is <code>null</code>.
076       * @throws NullPointerException if <code>matcher</code> is <code>null</code>.
077       */
078      void printComponents(PrintStream out, ComponentMatcher matcher);
079    
080      /**
081       * Prints all the components that match the given search criteria under the given root.
082       * @param out the output stream where to print the components to.
083       * @param matcher specifies the search criteria to use filter the components to print.
084       * @param root the root used as the starting point of the search.
085       * @see Formatting#format(Component)
086       * @throws NullPointerException if the output stream is <code>null</code>.
087       * @throws NullPointerException if <code>matcher</code> is <code>null</code>.
088       */
089      void printComponents(PrintStream out,  ComponentMatcher matcher, Container root);
090    }