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