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 }
|