1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 2 /* */ 3 /* This file is part of the program and library */ 4 /* SCIP --- Solving Constraint Integer Programs */ 5 /* */ 6 /* Copyright (c) 2002-2023 Zuse Institute Berlin (ZIB) */ 7 /* */ 8 /* Licensed under the Apache License, Version 2.0 (the "License"); */ 9 /* you may not use this file except in compliance with the License. */ 10 /* You may obtain a copy of the License at */ 11 /* */ 12 /* http://www.apache.org/licenses/LICENSE-2.0 */ 13 /* */ 14 /* Unless required by applicable law or agreed to in writing, software */ 15 /* distributed under the License is distributed on an "AS IS" BASIS, */ 16 /* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */ 17 /* See the License for the specific language governing permissions and */ 18 /* limitations under the License. */ 19 /* */ 20 /* You should have received a copy of the Apache-2.0 license */ 21 /* along with SCIP; see the file LICENSE. If not visit scipopt.org. */ 22 /* */ 23 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 24 25 /**@file pub_dialog.h 26 * @ingroup PUBLICCOREAPI 27 * @brief public methods for user interface dialog 28 * @author Tobias Achterberg 29 */ 30 31 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ 32 33 #ifndef __SCIP_PUB_DIALOG_H__ 34 #define __SCIP_PUB_DIALOG_H__ 35 36 37 #include "scip/def.h" 38 #include "scip/type_retcode.h" 39 #include "scip/type_scip.h" 40 #include "scip/type_dialog.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /* 47 * dialog handler 48 */ 49 50 /**@addtogroup PublicDialogMethods 51 * 52 * @{ 53 */ 54 /** returns the root dialog of the dialog handler */ 55 SCIP_EXPORT 56 SCIP_DIALOG* SCIPdialoghdlrGetRoot( 57 SCIP_DIALOGHDLR* dialoghdlr /**< dialog handler */ 58 ); 59 60 /** clears the input command buffer of the dialog handler */ 61 SCIP_EXPORT 62 void SCIPdialoghdlrClearBuffer( 63 SCIP_DIALOGHDLR* dialoghdlr /**< dialog handler */ 64 ); 65 66 /** returns TRUE iff input command buffer is empty */ 67 SCIP_EXPORT 68 SCIP_Bool SCIPdialoghdlrIsBufferEmpty( 69 SCIP_DIALOGHDLR* dialoghdlr /**< dialog handler */ 70 ); 71 72 /** returns the next line in the handler's command buffer; if the buffer is empty, displays the given prompt or the 73 * current dialog's path and asks the user for further input; the user must not free or modify the returned string 74 */ 75 SCIP_EXPORT 76 SCIP_RETCODE SCIPdialoghdlrGetLine( 77 SCIP_DIALOGHDLR* dialoghdlr, /**< dialog handler */ 78 SCIP_DIALOG* dialog, /**< current dialog */ 79 const char* prompt, /**< prompt to display, or NULL to display the current dialog's path */ 80 char** inputline, /**< pointer to store the complete line in the handler's command buffer */ 81 SCIP_Bool* endoffile /**< pointer to store whether the end of the input file was reached */ 82 ); 83 84 /** returns the next word in the handler's command buffer; if the buffer is empty, displays the given prompt or the 85 * current dialog's path and asks the user for further input; the user must not free or modify the returned string 86 */ 87 SCIP_EXPORT 88 SCIP_RETCODE SCIPdialoghdlrGetWord( 89 SCIP_DIALOGHDLR* dialoghdlr, /**< dialog handler */ 90 SCIP_DIALOG* dialog, /**< current dialog */ 91 const char* prompt, /**< prompt to display, or NULL to display the current dialog's path */ 92 char** inputword, /**< pointer to store the next word in the handler's command buffer */ 93 SCIP_Bool* endoffile /**< pointer to store whether the end of the input file was reached */ 94 ); 95 96 /** adds a single line of input to the dialog handler which is treated as if the user entered the command line */ 97 SCIP_EXPORT 98 SCIP_RETCODE SCIPdialoghdlrAddInputLine( 99 SCIP_DIALOGHDLR* dialoghdlr, /**< dialog handler */ 100 const char* inputline /**< input line to add */ 101 ); 102 103 /** adds a command to the command history of the dialog handler; if a dialog is given, the command is preceeded 104 * by the dialog's command path; if no command is given, only the path to the dialog is added to the command history 105 */ 106 SCIP_EXPORT 107 SCIP_RETCODE SCIPdialoghdlrAddHistory( 108 SCIP_DIALOGHDLR* dialoghdlr, /**< dialog handler */ 109 SCIP_DIALOG* dialog, /**< current dialog, or NULL */ 110 const char* command, /**< command string to add to the command history, or NULL */ 111 SCIP_Bool escapecommand /**< should special characters in command be prefixed by an escape char? */ 112 ); 113 114 115 116 117 /* 118 * dialog 119 */ 120 121 /** returns TRUE iff a dialog entry matching exactly the given name is existing in the given dialog */ 122 SCIP_EXPORT 123 SCIP_Bool SCIPdialogHasEntry( 124 SCIP_DIALOG* dialog, /**< dialog */ 125 const char* entryname /**< name of the dialog entry to find */ 126 ); 127 128 /** searches the dialog for entries corresponding to the given name; 129 * If a complete match is found, the entry is returned as "subdialog" and 130 * the return value is 1. 131 * If no dialog entry completely matches the given "entryname", the number 132 * of entries with names beginning with "entryname" is returned. If this 133 * number is 1, the single match is returned as "subdialog". Otherwise, 134 * "subdialog" is set to NULL. 135 */ 136 SCIP_EXPORT 137 int SCIPdialogFindEntry( 138 SCIP_DIALOG* dialog, /**< dialog */ 139 const char* entryname, /**< name of the dialog entry to find */ 140 SCIP_DIALOG** subdialog /**< pointer to store the found dialog entry */ 141 ); 142 143 /** displays the dialog's menu */ 144 SCIP_EXPORT 145 SCIP_RETCODE SCIPdialogDisplayMenu( 146 SCIP_DIALOG* dialog, /**< dialog */ 147 SCIP* scip /**< SCIP data structure */ 148 ); 149 150 /** displays the entry for the dialog in it's parent's menu */ 151 SCIP_EXPORT 152 SCIP_RETCODE SCIPdialogDisplayMenuEntry( 153 SCIP_DIALOG* dialog, /**< dialog */ 154 SCIP* scip /**< SCIP data structure */ 155 ); 156 157 /** displays all dialog entries with names starting with the given "entryname" */ 158 SCIP_EXPORT 159 SCIP_RETCODE SCIPdialogDisplayCompletions( 160 SCIP_DIALOG* dialog, /**< dialog */ 161 SCIP* scip, /**< SCIP data structure */ 162 const char* entryname /**< name of the dialog entry to find */ 163 ); 164 165 /** gets the name of the current path in the dialog tree, separated by the given character */ 166 SCIP_EXPORT 167 void SCIPdialogGetPath( 168 SCIP_DIALOG* dialog, /**< dialog */ 169 const char sepchar, /**< separation character to insert in path */ 170 char* path /**< string buffer to store the path */ 171 ); 172 173 /** gets the command name of the dialog */ 174 SCIP_EXPORT 175 const char* SCIPdialogGetName( 176 SCIP_DIALOG* dialog /**< dialog */ 177 ); 178 179 /** gets the description of the dialog */ 180 SCIP_EXPORT 181 const char* SCIPdialogGetDesc( 182 SCIP_DIALOG* dialog /**< dialog */ 183 ); 184 185 /** returns whether the dialog is a sub menu */ 186 SCIP_EXPORT 187 SCIP_Bool SCIPdialogIsSubmenu( 188 SCIP_DIALOG* dialog /**< dialog */ 189 ); 190 191 /** gets the parent dialog of the given dialog */ 192 SCIP_EXPORT 193 SCIP_DIALOG* SCIPdialogGetParent( 194 SCIP_DIALOG* dialog /**< dialog */ 195 ); 196 197 /** gets the array of sub-dialogs associated with the given dialog */ 198 SCIP_EXPORT 199 SCIP_DIALOG** SCIPdialogGetSubdialogs( 200 SCIP_DIALOG* dialog /**< dialog */ 201 ); 202 203 /** gets the number of sub-dialogs associated with the given dialog */ 204 SCIP_EXPORT 205 int SCIPdialogGetNSubdialogs( 206 SCIP_DIALOG* dialog /**< dialog */ 207 ); 208 209 /** gets the user defined data associated with the given dialog */ 210 SCIP_EXPORT 211 SCIP_DIALOGDATA* SCIPdialogGetData( 212 SCIP_DIALOG* dialog /**< dialog */ 213 ); 214 215 /** sets user data of dialog; user has to free old data in advance! */ 216 SCIP_EXPORT 217 void SCIPdialogSetData( 218 SCIP_DIALOG* dialog, /**< dialog */ 219 SCIP_DIALOGDATA* dialogdata /**< new dialog user data */ 220 ); 221 222 /** writes command history to specified filename */ 223 SCIP_EXPORT 224 SCIP_RETCODE SCIPdialogWriteHistory( 225 const char* filename /**< file name for (over)writing history */ 226 ); 227 228 /** @} */ 229 230 #ifdef __cplusplus 231 } 232 #endif 233 234 #endif 235