1 /*
2  * Copyright (C) 2020 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.cts.helpers;
18 
19 /** Helper methods for interacting with the print system UI. */
20 public interface ICtsPrintHelper extends ICtsDeviceInteractionHelper {
21 
22     /**
23      * Submit a print job based on the current settings.
24      *
25      * <p>This is the equivalent of the user clicking the print button; the test app must have
26      * already called PrintManager.print() to create the print job and start the UI.
27      */
submitPrintJob()28     void submitPrintJob();
29 
30     /**
31      * Retry a failed print job with the current settings.
32      *
33      * <p>This is the equivalent of the user clicking the "Retry" action button in the
34      * print error fragment.
35      */
retryPrintJob()36     void retryPrintJob();
37 
38     /**
39      * Check if the print job can be submitted.
40      *
41      * <p>A print job can be submitted when a valid printer is selected and all of the options
42      * contain valid values.
43      *
44      * @return true if the print button is enabled, false if not.
45      */
canSubmitJob()46     boolean canSubmitJob();
47 
48     /**
49      * Respond to the first-time dialog when printing to a new service.
50      *
51      * @param confirm true to accept printing, or false to cancel.
52      */
answerPrintServicesWarning(boolean confirm)53     void answerPrintServicesWarning(boolean confirm);
54 
55     /**
56      * Select a specific printer from the list of available printers.
57      *
58      * @param printerName name of the printer
59      * @param timeout timeout in milliseconds
60      */
selectPrinter(String printerName, long timeout)61     void selectPrinter(String printerName, long timeout);
62 
63     /**
64      * Wait for a printer to appear in the list of printers, then select it.
65      *
66      * <p>This is similar to {@link #selectPrinter(String, long)}, except it retries until the
67      * printer exists.  Can be used if a printer has just been added and might not yet be available.
68      *
69      * @param printerName name of the printer
70      */
selectPrinterWhenAvailable(String printerName)71     void selectPrinterWhenAvailable(String printerName);
72 
73     /**
74      * Set the page orientation to portrait or landscape.
75      *
76      * @param orientation "Portrait" or "Landscape"
77      */
setPageOrientation(String orientation)78     void setPageOrientation(String orientation);
79 
80     /**
81      * Get the current page orientation.
82      *
83      * @return current orientation as "Portrait" or "Landscape"
84      */
getPageOrientation()85     String getPageOrientation();
86 
87     /**
88      * Set the media size.
89      *
90      * @param mediaSize human-readable label matching one of the PrintAttributes.MediaSize values
91      */
setMediaSize(String mediaSize)92     void setMediaSize(String mediaSize);
93 
94     /**
95      * Set the color mode to Color or Black &amp; White.
96      *
97      * @param color "Color" or "Black &amp; White"
98      */
setColorMode(String color)99     void setColorMode(String color);
100 
101     /**
102      * Get the current color mode.
103      *
104      * @return "Color" or "Black &amp; White"
105      */
getColorMode()106     String getColorMode();
107 
108     /**
109      * Set the duplex mode.
110      *
111      * @param duplex human-readable label matching one of the DUPLEX_MODE constants from
112      *               PrintAttributes
113      */
setDuplexMode(String duplex)114     void setDuplexMode(String duplex);
115 
116     /**
117      * Set the number of copies to print.
118      *
119      * @param copies the new number of copies
120      */
setCopies(int copies)121     void setCopies(int copies);
122 
123     /**
124      * Get the current number of copies to print.
125      *
126      * @return the current number of copies
127      */
getCopies()128     int getCopies();
129 
130     /**
131      * Set the page range to print.
132      *
133      * @param pages a range to print, e.g. "1", "1, 3"
134      * @param expectedPages the total number of pages included in the range
135      */
setPageRange(String pages, int expectedPages)136     void setPageRange(String pages, int expectedPages);
137 
138     /**
139      * Get the current page range.
140      *
141      * <p>If the full page range is selected, "All N" will be returned, where N is the number of
142      * pages passed in docPages.  Otherwise, the user's entered range string will be returned.
143      *
144      * @param docPages the total number of pages in the doc.
145      *
146      * @return the current page range, e.g. "All 3", "1-2", "1, 3"
147      */
getPageRange(int docPages)148     String getPageRange(int docPages);
149 
150     /**
151      * Get the current status message.
152      *
153      * @return the text content of the current status message
154      */
getStatusMessage()155     String getStatusMessage();
156 
157     /**
158      * Ensure the basic print options are visible.
159      *
160      * <p>This is the equivalent of clicking the chevron to expose the basic print options.
161      */
openPrintOptions()162     void openPrintOptions();
163 
164     /**
165      * Ensure the custom print options are visible.
166      *
167      * <p>This is the equivalent of clicking the "more options" button to open the print service's
168      * custom print options.  openPrintOptions() must have been called first to expose the basic
169      * print options.
170      */
openCustomPrintOptions()171     void openCustomPrintOptions();
172 
173     /**
174      * Display the full list of printers.
175      *
176      * <p>This is not intended for selecting a printer; use {@link #selectPrinter(String, long)} for
177      * that.  The purpose of displaying the whole list is to ensure that all printers can be
178      * successfully enumerated and have their properties retrieved.
179      */
displayPrinterList()180     void displayPrinterList();
181 
182     /**
183      * Display the "more info" activity for the currently selected printer.
184      */
displayMoreInfo()185     void displayMoreInfo();
186 
187     /**
188      * Close the printer list that was previously opened with {@link #displayPrinterList()}.
189      */
closePrinterList()190     void closePrinterList();
191 
192     /**
193      * Close the custom print options that were previously opened with
194      * {@link #openCustomPrintOptions()}.
195      *
196      * This call must be properly nested with other calls to openPrintOptions/closePrintOptions and
197      * print/cancelPrinting.
198      */
closeCustomPrintOptions()199     void closeCustomPrintOptions();
200 
201     /**
202      * Close the basic print options that were previously opened with {@link #openPrintOptions()}.
203      *
204      * This call must be properly nested with other calls to
205      * openCustomPrintOptions/closeCustomPrintOptions and print/cancelPrinting.
206      */
closePrintOptions()207     void closePrintOptions();
208 
209     /**
210      * Close the main print UI that as previously opened with {@link PrintManager.print()}.
211      *
212      * This call must be properly nested with other calls to
213      * openCustomPrintOptions/closeCustomPrintOptions and openPrintOptions/closePrintOptions.
214      */
cancelPrinting()215     void cancelPrinting();
216 }
217