WindowManager.java
001 /*
002  * Copyright 2008-2014 the original author or authors.
003  *
004  * Licensed under the Apache License, Version 2.0 (the "License");
005  * you may not use this file except in compliance with the License.
006  * You may obtain a copy of the License at
007  *
008  *     http://www.apache.org/licenses/LICENSE-2.0
009  *
010  * Unless required by applicable law or agreed to in writing, software
011  * distributed under the License is distributed on an "AS IS" BASIS,
012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013  * See the License for the specific language governing permissions and
014  * limitations under the License.
015  */
016 package griffon.core.view;
017 
018 import griffon.core.GriffonApplication;
019 import griffon.core.ShutdownHandler;
020 
021 import javax.annotation.Nonnull;
022 import javax.annotation.Nullable;
023 import java.util.Collection;
024 
025 /**
026  * Controls a set of windows that belong to the application.<p>
027  * Windows that are controlled by a WindowManager can be shown/hidden
028  * using a custom strategy ({@code WindowDisplayHandler})
029  *
030  @author Andres Almiray
031  @since 2.0.0
032  */
033 public interface WindowManager<W> extends ShutdownHandler {
034     /**
035      * Finds a Window by name.
036      *
037      @param name the value of the of the Window's name
038      @return a Window if a match is found, null otherwise.
039      */
040     @Nullable
041     W findWindow(@Nonnull String name);
042 
043     /**
044      * Convenience method to get a managed Window by index.<p>
045      * Follows the Groovy conventions for overriding the [] operator.
046      *
047      @param index the index of the Window to be retrieved
048      @return the Window found at the specified index
049      @throws ArrayIndexOutOfBoundsException if the index is invalid (below 0 or greater than the size
050      *                                        of the managed windows list)
051      */
052     @Nullable
053     W getAt(int index);
054 
055     /**
056      * Finds the Window that should be displayed during the Ready phase of an application.<p>
057      * The WindowManager expects a configuration flag <code>windowManager.startingWindow</code> to be
058      * present in order to determine which Window will be displayed during the Ready phase. If no configuration
059      * is found the WindowManager will pick the first Window found in the list of managed windows.<p>
060      * The configuration flag accepts two value types:<ul>
061      <li>a String that defines the name of the Window. You must make sure the Window has a matching name property.</li>
062      <li>a Number that defines the index of the Window in the list of managed windows.</li>
063      </ul>
064      *
065      @return a Window that matches the given criteria or null if no match is found.
066      */
067     @Nullable
068     W getStartingWindow();
069 
070     /**
071      * Returns the list of windows managed by this manager.
072      *
073      @return a List of currently managed windows
074      */
075     @Nonnull
076     Collection<W> getWindows();
077 
078     /**
079      * Registers a window on this manager if an only if the window is not null
080      * and it's not registered already.
081      *
082      @param name   the value of the of the Window's name
083      @param window the window to be added to the list of managed windows
084      */
085     void attach(@Nonnull String name, @Nonnull W window);
086 
087     /**
088      * Removes the window from the list of manages windows if and only if it
089      * is registered with this manager.
090      *
091      @param name the value of the of the Window's name
092      */
093     void detach(@Nonnull String name);
094 
095     /**
096      * Shows the window.<p>
097      * This method is executed <b>SYNCHRONOUSLY</b> in the UI thread.
098      *
099      @param window the window to show
100      */
101     void show(@Nonnull W window);
102 
103     /**
104      * Shows the window.<p>
105      * This method is executed <b>SYNCHRONOUSLY</b> in the UI thread.
106      *
107      @param name the name of window to show
108      */
109     void show(@Nonnull String name);
110 
111     /**
112      * Hides the window.<p>
113      * This method is executed <b>SYNCHRONOUSLY</b> in the UI thread.
114      *
115      @param window the window to hide
116      */
117     void hide(@Nonnull W window);
118 
119     /**
120      * Hides the window.<p>
121      * This method is executed <b>SYNCHRONOUSLY</b> in the UI thread.
122      *
123      @param name the name of window to hide
124      */
125     void hide(@Nonnull String name);
126 
127     boolean canShutdown(@Nonnull GriffonApplication app);
128 
129     /**
130      * Hides all visible windows
131      */
132     void onShutdown(@Nonnull GriffonApplication app);
133 
134     /**
135      * Counts how many Windows are visible regardless of their attached status to this WindowManager.
136      *
137      @return the number of visible Windows
138      */
139     int countVisibleWindows();
140 
141     /**
142      * Returns the value of the "application.autoShutdown" configuration flag.
143      *
144      @return the value of the "application.autoShutdown" configuration flag.
145      */
146     boolean isAutoShutdown();
147 }