1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.OptionContext; 26 27 private import glib.ConstructionException; 28 private import glib.ErrorG; 29 private import glib.GException; 30 private import glib.OptionGroup; 31 private import glib.Str; 32 private import gtkc.glib; 33 public import gtkc.glibtypes; 34 35 36 /** 37 * A `GOptionContext` struct defines which options 38 * are accepted by the commandline option parser. The struct has only private 39 * fields and should not be directly accessed. 40 */ 41 public class OptionContext 42 { 43 /** the main Gtk struct */ 44 protected GOptionContext* gOptionContext; 45 46 /** Get the main Gtk struct */ 47 public GOptionContext* getOptionContextStruct() 48 { 49 return gOptionContext; 50 } 51 52 /** the main Gtk struct as a void* */ 53 protected void* getStruct() 54 { 55 return cast(void*)gOptionContext; 56 } 57 58 /** 59 * Sets our main struct and passes it to the parent class. 60 */ 61 public this (GOptionContext* gOptionContext) 62 { 63 this.gOptionContext = gOptionContext; 64 } 65 66 /** 67 */ 68 69 /** 70 * Adds a #GOptionGroup to the @context, so that parsing with @context 71 * will recognize the options in the group. Note that the group will 72 * be freed together with the context when g_option_context_free() is 73 * called, so you must not free the group yourself after adding it 74 * to a context. 75 * 76 * Params: 77 * group = the group to add 78 * 79 * Since: 2.6 80 */ 81 public void addGroup(OptionGroup group) 82 { 83 g_option_context_add_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct()); 84 } 85 86 /** 87 * A convenience function which creates a main group if it doesn't 88 * exist, adds the @entries to it and sets the translation domain. 89 * 90 * Params: 91 * entries = a %NULL-terminated array of #GOptionEntrys 92 * translationDomain = a translation domain to use for translating 93 * the `--help` output for the options in @entries 94 * with gettext(), or %NULL 95 * 96 * Since: 2.6 97 */ 98 public void addMainEntries(GOptionEntry* entries, string translationDomain) 99 { 100 g_option_context_add_main_entries(gOptionContext, entries, Str.toStringz(translationDomain)); 101 } 102 103 /** 104 * Frees context and all the groups which have been 105 * added to it. 106 * 107 * Please note that parsed arguments need to be freed separately (see 108 * #GOptionEntry). 109 * 110 * Since: 2.6 111 */ 112 public void free() 113 { 114 g_option_context_free(gOptionContext); 115 } 116 117 /** 118 * Returns the description. See g_option_context_set_description(). 119 * 120 * Return: the description 121 * 122 * Since: 2.12 123 */ 124 public string getDescription() 125 { 126 return Str.toString(g_option_context_get_description(gOptionContext)); 127 } 128 129 /** 130 * Returns a formatted, translated help text for the given context. 131 * To obtain the text produced by `--help`, call 132 * `g_option_context_get_help (context, TRUE, NULL)`. 133 * To obtain the text produced by `--help-all`, call 134 * `g_option_context_get_help (context, FALSE, NULL)`. 135 * To obtain the help text for an option group, call 136 * `g_option_context_get_help (context, FALSE, group)`. 137 * 138 * Params: 139 * mainHelp = if %TRUE, only include the main group 140 * group = the #GOptionGroup to create help for, or %NULL 141 * 142 * Return: A newly allocated string containing the help text 143 * 144 * Since: 2.14 145 */ 146 public string getHelp(bool mainHelp, OptionGroup group) 147 { 148 return Str.toString(g_option_context_get_help(gOptionContext, mainHelp, (group is null) ? null : group.getOptionGroupStruct())); 149 } 150 151 /** 152 * Returns whether automatic `--help` generation 153 * is turned on for @context. See g_option_context_set_help_enabled(). 154 * 155 * Return: %TRUE if automatic help generation is turned on. 156 * 157 * Since: 2.6 158 */ 159 public bool getHelpEnabled() 160 { 161 return g_option_context_get_help_enabled(gOptionContext) != 0; 162 } 163 164 /** 165 * Returns whether unknown options are ignored or not. See 166 * g_option_context_set_ignore_unknown_options(). 167 * 168 * Return: %TRUE if unknown options are ignored. 169 * 170 * Since: 2.6 171 */ 172 public bool getIgnoreUnknownOptions() 173 { 174 return g_option_context_get_ignore_unknown_options(gOptionContext) != 0; 175 } 176 177 /** 178 * Returns a pointer to the main group of @context. 179 * 180 * Return: the main group of @context, or %NULL if @context doesn't 181 * have a main group. Note that group belongs to @context and should 182 * not be modified or freed. 183 * 184 * Since: 2.6 185 */ 186 public OptionGroup getMainGroup() 187 { 188 auto p = g_option_context_get_main_group(gOptionContext); 189 190 if(p is null) 191 { 192 return null; 193 } 194 195 return new OptionGroup(cast(GOptionGroup*) p); 196 } 197 198 /** 199 * Returns the summary. See g_option_context_set_summary(). 200 * 201 * Return: the summary 202 * 203 * Since: 2.12 204 */ 205 public string getSummary() 206 { 207 return Str.toString(g_option_context_get_summary(gOptionContext)); 208 } 209 210 /** 211 * Parses the command line arguments, recognizing options 212 * which have been added to @context. A side-effect of 213 * calling this function is that g_set_prgname() will be 214 * called. 215 * 216 * If the parsing is successful, any parsed arguments are 217 * removed from the array and @argc and @argv are updated 218 * accordingly. A '--' option is stripped from @argv 219 * unless there are unparsed options before and after it, 220 * or some of the options after it start with '-'. In case 221 * of an error, @argc and @argv are left unmodified. 222 * 223 * If automatic `--help` support is enabled 224 * (see g_option_context_set_help_enabled()), and the 225 * @argv array contains one of the recognized help options, 226 * this function will produce help output to stdout and 227 * call `exit (0)`. 228 * 229 * Note that function depends on the [current locale][setlocale] for 230 * automatic character set conversion of string and filename 231 * arguments. 232 * 233 * Params: 234 * argc = a pointer to the number of command line arguments 235 * argv = a pointer to the array of command line arguments 236 * 237 * Return: %TRUE if the parsing was successful, 238 * %FALSE if an error occurred 239 * 240 * Since: 2.6 241 * 242 * Throws: GException on failure. 243 */ 244 public bool parse(ref string[] argv) 245 { 246 int argc = cast(int)argv.length; 247 char** outargv = Str.toStringzArray(argv); 248 GError* err = null; 249 250 auto p = g_option_context_parse(gOptionContext, &argc, &outargv, &err) != 0; 251 252 if (err !is null) 253 { 254 throw new GException( new ErrorG(err) ); 255 } 256 257 argv = Str.toStringArray(outargv, argc); 258 259 return p; 260 } 261 262 /** 263 * Parses the command line arguments. 264 * 265 * This function is similar to g_option_context_parse() except that it 266 * respects the normal memory rules when dealing with a strv instead of 267 * assuming that the passed-in array is the argv of the main function. 268 * 269 * In particular, strings that are removed from the arguments list will 270 * be freed using g_free(). 271 * 272 * On Windows, the strings are expected to be in UTF-8. This is in 273 * contrast to g_option_context_parse() which expects them to be in the 274 * system codepage, which is how they are passed as @argv to main(). 275 * See g_win32_get_command_line() for a solution. 276 * 277 * This function is useful if you are trying to use #GOptionContext with 278 * #GApplication. 279 * 280 * Params: 281 * arguments = a pointer to the 282 * command line arguments (which must be in UTF-8 on Windows) 283 * 284 * Return: %TRUE if the parsing was successful, 285 * %FALSE if an error occurred 286 * 287 * Since: 2.40 288 * 289 * Throws: GException on failure. 290 */ 291 public bool parseStrv(ref string[] arguments) 292 { 293 char** outarguments = Str.toStringzArray(arguments); 294 GError* err = null; 295 296 auto p = g_option_context_parse_strv(gOptionContext, &outarguments, &err) != 0; 297 298 if (err !is null) 299 { 300 throw new GException( new ErrorG(err) ); 301 } 302 303 arguments = Str.toStringArray(outarguments); 304 305 return p; 306 } 307 308 /** 309 * Adds a string to be displayed in `--help` output after the list 310 * of options. This text often includes a bug reporting address. 311 * 312 * Note that the summary is translated (see 313 * g_option_context_set_translate_func()). 314 * 315 * Params: 316 * description = a string to be shown in `--help` output 317 * after the list of options, or %NULL 318 * 319 * Since: 2.12 320 */ 321 public void setDescription(string description) 322 { 323 g_option_context_set_description(gOptionContext, Str.toStringz(description)); 324 } 325 326 /** 327 * Enables or disables automatic generation of `--help` output. 328 * By default, g_option_context_parse() recognizes `--help`, `-h`, 329 * `-?`, `--help-all` and `--help-groupname` and creates suitable 330 * output to stdout. 331 * 332 * Params: 333 * helpEnabled = %TRUE to enable `--help`, %FALSE to disable it 334 * 335 * Since: 2.6 336 */ 337 public void setHelpEnabled(bool helpEnabled) 338 { 339 g_option_context_set_help_enabled(gOptionContext, helpEnabled); 340 } 341 342 /** 343 * Sets whether to ignore unknown options or not. If an argument is 344 * ignored, it is left in the @argv array after parsing. By default, 345 * g_option_context_parse() treats unknown options as error. 346 * 347 * This setting does not affect non-option arguments (i.e. arguments 348 * which don't start with a dash). But note that GOption cannot reliably 349 * determine whether a non-option belongs to a preceding unknown option. 350 * 351 * Params: 352 * ignoreUnknown = %TRUE to ignore unknown options, %FALSE to produce 353 * an error when unknown options are met 354 * 355 * Since: 2.6 356 */ 357 public void setIgnoreUnknownOptions(bool ignoreUnknown) 358 { 359 g_option_context_set_ignore_unknown_options(gOptionContext, ignoreUnknown); 360 } 361 362 /** 363 * Sets a #GOptionGroup as main group of the @context. 364 * This has the same effect as calling g_option_context_add_group(), 365 * the only difference is that the options in the main group are 366 * treated differently when generating `--help` output. 367 * 368 * Params: 369 * group = the group to set as main group 370 * 371 * Since: 2.6 372 */ 373 public void setMainGroup(OptionGroup group) 374 { 375 g_option_context_set_main_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct()); 376 } 377 378 /** 379 * Adds a string to be displayed in `--help` output before the list 380 * of options. This is typically a summary of the program functionality. 381 * 382 * Note that the summary is translated (see 383 * g_option_context_set_translate_func() and 384 * g_option_context_set_translation_domain()). 385 * 386 * Params: 387 * summary = a string to be shown in `--help` output 388 * before the list of options, or %NULL 389 * 390 * Since: 2.12 391 */ 392 public void setSummary(string summary) 393 { 394 g_option_context_set_summary(gOptionContext, Str.toStringz(summary)); 395 } 396 397 /** 398 * Sets the function which is used to translate the contexts 399 * user-visible strings, for `--help` output. If @func is %NULL, 400 * strings are not translated. 401 * 402 * Note that option groups have their own translation functions, 403 * this function only affects the @parameter_string (see g_option_context_new()), 404 * the summary (see g_option_context_set_summary()) and the description 405 * (see g_option_context_set_description()). 406 * 407 * If you are using gettext(), you only need to set the translation 408 * domain, see g_option_context_set_translation_domain(). 409 * 410 * Params: 411 * func = the #GTranslateFunc, or %NULL 412 * data = user data to pass to @func, or %NULL 413 * destroyNotify = a function which gets called to free @data, or %NULL 414 * 415 * Since: 2.12 416 */ 417 public void setTranslateFunc(GTranslateFunc func, void* data, GDestroyNotify destroyNotify) 418 { 419 g_option_context_set_translate_func(gOptionContext, func, data, destroyNotify); 420 } 421 422 /** 423 * A convenience function to use gettext() for translating 424 * user-visible strings. 425 * 426 * Params: 427 * domain = the domain to use 428 * 429 * Since: 2.12 430 */ 431 public void setTranslationDomain(string domain) 432 { 433 g_option_context_set_translation_domain(gOptionContext, Str.toStringz(domain)); 434 } 435 436 /** 437 * Creates a new option context. 438 * 439 * The @parameter_string can serve multiple purposes. It can be used 440 * to add descriptions for "rest" arguments, which are not parsed by 441 * the #GOptionContext, typically something like "FILES" or 442 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for 443 * collecting "rest" arguments, GLib handles this automatically by 444 * using the @arg_description of the corresponding #GOptionEntry in 445 * the usage summary. 446 * 447 * Another usage is to give a short summary of the program 448 * functionality, like " - frob the strings", which will be displayed 449 * in the same line as the usage. For a longer description of the 450 * program functionality that should be displayed as a paragraph 451 * below the usage line, use g_option_context_set_summary(). 452 * 453 * Note that the @parameter_string is translated using the 454 * function set with g_option_context_set_translate_func(), so 455 * it should normally be passed untranslated. 456 * 457 * Params: 458 * parameterString = a string which is displayed in 459 * the first line of `--help` output, after the usage summary 460 * `programname [OPTION...]` 461 * 462 * Return: a newly created #GOptionContext, which must be 463 * freed with g_option_context_free() after use. 464 * 465 * Since: 2.6 466 * 467 * Throws: ConstructionException GTK+ fails to create the object. 468 */ 469 public this(string parameterString) 470 { 471 auto p = g_option_context_new(Str.toStringz(parameterString)); 472 473 if(p is null) 474 { 475 throw new ConstructionException("null returned by new"); 476 } 477 478 this(cast(GOptionContext*) p); 479 } 480 481 public static GQuark optionErrorQuark() 482 { 483 return g_option_error_quark(); 484 } 485 }