1 /* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.sdklib.internal.repository; 18 19 import com.android.sdklib.ISdkLog; 20 import com.android.util.Pair; 21 22 23 /** 24 * A monitor interface for a {@link ITask}. 25 * <p/> 26 * Depending on the task factory that created the task, there might not be any UI 27 * or it might not implement all the methods, in which case calling them would be 28 * a no-op but is guaranteed not to crash. 29 * <p/> 30 * If the task runs in a non-UI worker thread, the task factory implementation 31 * will take care of the update the UI in the correct thread. The task itself 32 * must not have to deal with it. 33 * <p/> 34 * A monitor typically has 3 levels of text displayed: <br/> 35 * - A <b>title</b> <em>may</em> be present on a task dialog, typically when a task 36 * dialog is created. This is not covered by this monitor interface. <br/> 37 * - A <b>description</b> displays prominent information on what the task 38 * is currently doing. This is expected to vary over time, typically changing 39 * with each sub-monitor, and typically only the last description is visible. 40 * For example an updater would typically have descriptions such as "downloading", 41 * "installing" and finally "done". This is set using {@link #setDescription}. <br/> 42 * - A <b>verbose</b> optional log that can provide more information than the summary 43 * description and is typically displayed in some kind of scrollable multi-line 44 * text field so that the user can keep track of what happened. 3 levels are 45 * provided: error, normal and verbose. An UI may hide the log till an error is 46 * logged and/or might hide the verbose text unless a flag is checked by the user. 47 * This is set using {@link #log}, {@link #logError} and {@link #logVerbose}. 48 * <p/> 49 * A monitor is also an {@link ISdkLog} implementation. 50 */ 51 public interface ITaskMonitor extends ISdkLog { 52 53 /** 54 * Sets the description in the current task dialog. 55 * This method can be invoked from a non-UI thread. 56 */ setDescription(String format, Object...args)57 public void setDescription(String format, Object...args); 58 59 /** 60 * Logs a "normal" information line. 61 * This method can be invoked from a non-UI thread. 62 */ log(String format, Object...args)63 public void log(String format, Object...args); 64 65 /** 66 * Logs an "error" information line. 67 * This method can be invoked from a non-UI thread. 68 */ logError(String format, Object...args)69 public void logError(String format, Object...args); 70 71 /** 72 * Logs a "verbose" information line, that is extra details which are typically 73 * not that useful for the end-user and might be hidden until explicitly shown. 74 * This method can be invoked from a non-UI thread. 75 */ logVerbose(String format, Object...args)76 public void logVerbose(String format, Object...args); 77 78 /** 79 * Sets the max value of the progress bar. 80 * This method can be invoked from a non-UI thread. 81 * 82 * This method MUST be invoked once before using {@link #incProgress(int)} or 83 * {@link #getProgress()} or {@link #createSubMonitor(int)}. Callers are 84 * discouraged from using more than once -- implementations can either discard 85 * the next calls or behave incoherently. 86 */ setProgressMax(int max)87 public void setProgressMax(int max); 88 89 /** 90 * Returns the max valie of the progress bar, as last set by {@link #setProgressMax(int)}. 91 * Returns 0 if the max has never been set yet. 92 */ getProgressMax()93 public int getProgressMax(); 94 95 /** 96 * Increments the current value of the progress bar. 97 * This method can be invoked from a non-UI thread. 98 * 99 * Callers MUST use setProgressMax before using this method. 100 */ incProgress(int delta)101 public void incProgress(int delta); 102 103 /** 104 * Returns the current value of the progress bar, 105 * between 0 and up to {@link #setProgressMax(int)} - 1. 106 * 107 * Callers MUST use setProgressMax before using this method. 108 */ getProgress()109 public int getProgress(); 110 111 /** 112 * Returns true if the user requested to cancel the operation. 113 * It is up to the task thread to pool this and exit as soon 114 * as possible. 115 */ isCancelRequested()116 public boolean isCancelRequested(); 117 118 /** 119 * Creates a sub-monitor that will use up to tickCount on the progress bar. 120 * tickCount must be 1 or more. 121 */ createSubMonitor(int tickCount)122 public ITaskMonitor createSubMonitor(int tickCount); 123 124 /** 125 * Display a yes/no question dialog box. 126 * 127 * Implementations MUST allow this to be called from any thread, e.g. by 128 * making sure the dialog is opened synchronously in the ui thread. 129 * 130 * @param title The title of the dialog box 131 * @param message The error message 132 * @return true if YES was clicked. 133 */ displayPrompt(final String title, final String message)134 public boolean displayPrompt(final String title, final String message); 135 136 /** 137 * Launch an interface which asks for login and password. Implementations 138 * MUST allow this to be called from any thread, e.g. by making sure the 139 * dialog is opened synchronously in the UI thread. 140 * 141 * @param title The title of the dialog box. 142 * @param message The message to be displayed as an instruction. 143 * @return Returns a {@link Pair} holding the entered login and password. 144 * The information must always be in the following order: 145 * Login,Password. So in order to retrieve the <b>login</b> callers 146 * should retrieve the first element, and the second value for the 147 * <b>password</b>. 148 If operation is <b>canceled</b> by user the return value must be <b>null</b>. 149 */ displayLoginPasswordPrompt(String title, String message)150 public Pair<String, String> displayLoginPasswordPrompt(String title, String message); 151 } 152