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 21 22 /** 23 * A monitor interface for a {@link ITask}. 24 * <p/> 25 * Depending on the task factory that created the task, there might not be any UI 26 * or it might not implement all the methods, in which case calling them would be 27 * a no-op but is guaranteed not to crash. 28 * <p/> 29 * If the task runs in a non-UI worker thread, the task factory implementation 30 * will take care of the update the UI in the correct thread. The task itself 31 * must not have to deal with it. 32 * <p/> 33 * A monitor typically has 3 levels of text displayed: <br/> 34 * - A <b>title</b> <em>may</em> be present on a task dialog, typically when a task 35 * dialog is created. This is not covered by this monitor interface. <br/> 36 * - A <b>description</b> displays prominent information on what the task 37 * is currently doing. This is expected to vary over time, typically changing 38 * with each sub-monitor, and typically only the last description is visible. 39 * For example an updater would typically have descriptions such as "downloading", 40 * "installing" and finally "done". This is set using {@link #setDescription}. <br/> 41 * - A <b>verbose</b> optional log that can provide more information than the summary 42 * description and is typically displayed in some kind of scrollable multi-line 43 * text field so that the user can keep track of what happened. 3 levels are 44 * provided: error, normal and verbose. An UI may hide the log till an error is 45 * logged and/or might hide the verbose text unless a flag is checked by the user. 46 * This is set using {@link #log}, {@link #logError} and {@link #logVerbose}. 47 * <p/> 48 * A monitor is also an {@link ISdkLog} implementation. 49 */ 50 public interface ITaskMonitor extends ISdkLog { 51 52 /** 53 * Sets the description in the current task dialog. 54 * This method can be invoked from a non-UI thread. 55 */ setDescription(String format, Object...args)56 public void setDescription(String format, Object...args); 57 58 /** 59 * Logs a "normal" information line. 60 * This method can be invoked from a non-UI thread. 61 */ log(String format, Object...args)62 public void log(String format, Object...args); 63 64 /** 65 * Logs an "error" information line. 66 * This method can be invoked from a non-UI thread. 67 */ logError(String format, Object...args)68 public void logError(String format, Object...args); 69 70 /** 71 * Logs a "verbose" information line, that is extra details which are typically 72 * not that useful for the end-user and might be hidden until explicitly shown. 73 * This method can be invoked from a non-UI thread. 74 */ logVerbose(String format, Object...args)75 public void logVerbose(String format, Object...args); 76 77 /** 78 * Sets the max value of the progress bar. 79 * This method can be invoked from a non-UI thread. 80 * 81 * This method MUST be invoked once before using {@link #incProgress(int)} or 82 * {@link #getProgress()} or {@link #createSubMonitor(int)}. Callers are 83 * discouraged from using more than once -- implementations can either discard 84 * the next calls or behave incoherently. 85 */ setProgressMax(int max)86 public void setProgressMax(int max); 87 88 /** 89 * Returns the max valie of the progress bar, as last set by {@link #setProgressMax(int)}. 90 * Returns 0 if the max has never been set yet. 91 */ getProgressMax()92 public int getProgressMax(); 93 94 /** 95 * Increments the current value of the progress bar. 96 * This method can be invoked from a non-UI thread. 97 * 98 * Callers MUST use setProgressMax before using this method. 99 */ incProgress(int delta)100 public void incProgress(int delta); 101 102 /** 103 * Returns the current value of the progress bar, 104 * between 0 and up to {@link #setProgressMax(int)} - 1. 105 * 106 * Callers MUST use setProgressMax before using this method. 107 */ getProgress()108 public int getProgress(); 109 110 /** 111 * Returns true if the user requested to cancel the operation. 112 * It is up to the task thread to pool this and exit as soon 113 * as possible. 114 */ isCancelRequested()115 public boolean isCancelRequested(); 116 117 /** 118 * Creates a sub-monitor that will use up to tickCount on the progress bar. 119 * tickCount must be 1 or more. 120 */ createSubMonitor(int tickCount)121 public ITaskMonitor createSubMonitor(int tickCount); 122 123 /** 124 * Display a yes/no question dialog box. 125 * 126 * Implementations MUST allow this to be called from any thread, e.g. by 127 * making sure the dialog is opened synchronously in the ui thread. 128 * 129 * @param title The title of the dialog box 130 * @param message The error message 131 * @return true if YES was clicked. 132 */ displayPrompt(final String title, final String message)133 public boolean displayPrompt(final String title, final String message); 134 135 /** 136 * Launch an interface which asks for user credentials. Implementations 137 * MUST allow this to be called from any thread, e.g. by making sure the 138 * dialog is opened synchronously in the UI thread. 139 * 140 * @param title The title of the dialog box. 141 * @param message The message to be displayed as an instruction. 142 * @return Returns the user provided credentials. Some fields may be blank if the user 143 * did not provide any input. 144 If operation is <b>canceled</b> by user the return value must be <b>null</b>. 145 */ displayLoginCredentialsPrompt(String title, String message)146 public UserCredentials displayLoginCredentialsPrompt(String title, String message); 147 } 148