Allow plugins to add entire screens to Gerrit

Add an extension screen which contains a hook that can be used by
GWT and JS plugins to integrate complete screens into the Gerrit UI.

Change-Id: I48a92ea49c4384db034177b04b2e7f0bea6a87b2

gerrit-plugin-gwtui/src/main/java/com/google/gerrit/Plugin.gwt.xml

@@ -14,6 +14,8 @@
  limitations under the License.
 -->
 <module>
+  <inherits name="com.google.gwt.json.JSON"/>
+
   <define-linker name="gerrit_plugin" class="com.google.gerrit.plugin.linker.GerritPluginLinker"/>
   <add-linker name="gerrit_plugin"/>
   <generate-with class="com.google.gerrit.plugin.rebind.PluginGenerator">

gerrit-plugin-gwtui/src/main/java/com/google/gerrit/plugin/client/Plugin.java

@@ -14,6 +14,7 @@
 
 package com.google.gerrit.plugin.client;
 
+import com.google.gerrit.plugin.client.screen.Screen;
 import com.google.gwt.core.client.GWT;
 import com.google.gwt.core.client.JavaScriptObject;
 
@@ -49,6 +50,35 @@ public final class Plugin extends JavaScriptObject {
   public final native void refresh()
   /*-{ return this.refresh() }-*/;
 
+  /**
+   * Register a screen displayed at {@code /#/x/plugin/token}.
+   *
+   * @param token literal anchor token appearing after the plugin name. For
+   *        regular expression matching use {@code screenRegex()} .
+   * @param entry callback function invoked to create the screen widgets.
+   */
+  public final void screen(String token, Screen.EntryPoint entry) {
+    screen(token, wrap(entry));
+  }
+
+  private final native void screen(String t, JavaScriptObject e)
+  /*-{ this.screen(t, e) }-*/;
+
+  /**
+   * Register a screen displayed at {@code /#/x/plugin/regex}.
+   *
+   * @param regex JavaScript {@code RegExp} expression to match the anchor token
+   *        after the plugin name. Matching groups are exposed through the
+   *        {@code Screen} object passed into the {@code Screen.EntryPoint}.
+   * @param entry callback function invoked to create the screen widgets.
+   */
+  public final void screenRegex(String regex, Screen.EntryPoint entry) {
+    screenRegex(regex, wrap(entry));
+  }
+
+  private final native void screenRegex(String p, JavaScriptObject e)
+  /*-{ this.screen(new $wnd.RegExp(p), e) }-*/;
+
   protected Plugin() {
   }
 
@@ -56,4 +86,11 @@ public final class Plugin extends JavaScriptObject {
   native void _loaded() /*-{ this._loadedGwt() }-*/;
   private static native final Plugin install(String u)
   /*-{ return $wnd.Gerrit.installGwt(u) }-*/;
+
+  private static final native JavaScriptObject wrap(Screen.EntryPoint b) /*-{
+    return $entry(function(c){
+      b.@com.google.gerrit.plugin.client.screen.Screen.EntryPoint::onLoad(Lcom/google/gerrit/plugin/client/screen/Screen;)(
+        @com.google.gerrit.plugin.client.screen.Screen::new(Lcom/google/gerrit/plugin/client/screen/Screen$Context;)(c));
+    });
+  }-*/;
 }

gerrit-plugin-gwtui/src/main/java/com/google/gerrit/plugin/client/screen/Screen.java

@@ -0,0 +1,140 @@
+// Copyright (C) 2013 The Android Open Source Project
+//
+// 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.google.gerrit.plugin.client.screen;
+
+import com.google.gwt.core.client.JavaScriptObject;
+import com.google.gwt.core.client.JsArrayString;
+import com.google.gwt.dom.client.Element;
+import com.google.gwt.user.client.ui.SimplePanel;
+import com.google.gwt.user.client.ui.Widget;
+
+/**
+ * Screen contributed by this plugin.
+ *
+ * Screens should be registered early at module load:
+ *
+ * <pre>
+ * &#064;Override
+ * public void onModuleLoad() {
+ *   Plugin.get().screen(&quot;hi&quot;, new Screen.EntryPoint() {
+ *     &#064;Override
+ *     public void onLoad(Screen screen) {
+ *       screen.setPageTitle(&quot;Hi&quot;);
+ *       screen.show(new Label(&quot;World&quot;));
+ *     }
+ *   });
+ * }
+ * </pre>
+ */
+public final class Screen extends SimplePanel {
+  /** Initializes a screen for display. */
+  public interface EntryPoint {
+    /**
+     * Invoked when the screen has been created, but not yet displayed.
+     * <p>
+     * The implementation should create a single widget to define the content of
+     * this screen and added it to the passed screen instance. When the screen
+     * is ready to be displayed, call {@link Screen#show()}.
+     * <p>
+     * To use multiple widgets, compose them in panels such as {@code FlowPanel}
+     * and add only the top level widget to the screen.
+     * <p>
+     * The screen is already attached to the browser DOM in an invisible area.
+     * Any widgets added to the screen will immediately receive {@code onLoad()}.
+     * GWT will fire {@code onUnload()} when the screen is removed from the UI,
+     * generally caused by the user navigating to another screen.
+     *
+     * @param screen panel that will contain the screen widget.
+     */
+    public void onLoad(Screen screen);
+  }
+
+  static final class Context extends JavaScriptObject {
+    final native Element body() /*-{ return this.body }-*/;
+    final native JsArrayString token_match() /*-{ return this.token_match }-*/;
+    final native void show() /*-{ this.show() }-*/;
+    final native void setTitle(String t) /*-{ this.setTitle(t) }-*/;
+    final native void setWindowTitle(String t) /*-{ this.setWindowTitle(t) }-*/;
+    final native void detach(Screen s) /*-{
+      this.onUnload($entry(function(){
+        s.@com.google.gwt.user.client.ui.Widget::onDetach()();
+      }));
+    }-*/;
+
+    protected Context() {
+    }
+  }
+
+  private final Context ctx;
+
+  Screen(Context ctx) {
+    super(ctx.body());
+    this.ctx = ctx;
+    onAttach();
+    ctx.detach(this);
+  }
+
+  /** @return the token suffix after {@code "/#/x/plugin-name/"}. */
+  public final String getToken() {
+    return getToken(0);
+  }
+
+  /**
+   * @param group groups range from 1 to {@code getTokenGroups() - 1}. Token
+   *        group 0 is the entire token, see {@link #getToken()}.
+   * @return the token from the regex match group.
+   */
+  public final String getToken(int group) {
+    return ctx.token_match().get(group);
+  }
+
+  /** @return total number of token groups. */
+  public final int getTokenGroups() {
+    return ctx.token_match().length();
+  }
+
+  /**
+   * Set the page title text; appears above the widget.
+   *
+   * @param titleText text to display above the widget.
+   */
+  public final void setPageTitle(String titleText) {
+    ctx.setTitle(titleText);
+  }
+
+  /**
+   * Set the window title text; appears in the browser window title bar.
+   *
+   * @param titleText text to display in the window title bar.
+   */
+  public final void setWindowTitle(String titleText) {
+    ctx.setWindowTitle(titleText);
+  }
+
+  /**
+   * Add the widget and immediately show the screen.
+   *
+   * @param w child containing the content.
+   */
+  public final void show(Widget w) {
+    setWidget(w);
+    ctx.show();
+  }
+
+  /** Show this screen in the web interface. */
+  public final void show() {
+    ctx.show();
+  }
+}