kdialog dialog types
The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.
Basic message boxes
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.
Example 8. Information level message box
kdialog --msgbox "Password correct.\n About to connect to server" |
A typical information level message box is shown below.
Example 9. Sorry level message box
kdialog --sorry "Password incorrect.\n Will not connect to server" |
A typical sorry level message box is shown below.
A typical error level message box is shown below.
The return value for these basic message boxes is zero.
While not used in these examples, you can use the --title to set the window title as well.
More message boxes
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.
A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.
Example 11. --yesno message box
kdialog --title "Example YesNo dialog" --yesno "System is not \ currently connected.\n Do you want to connect now?" |
A Yes/No message box is shown below.
A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.
Example 12. --warningyesno message box
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \ you sure you want to delete all that hard work?" |
A Yes/No warning box is shown below.
A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.
Example 13. --warningcontinuecancel message box
kdialog --title "Example ContinueCancel warning dialog" \ --warningcontinuecancel "Are you sure you want to delete all that \ hard work?" |
A Continue/Cancel warning box is shown below.
Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.
Example 14. --yesnocancel message box
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \ Do you want to save the file first?" |
A Yes/No/Cancel message box is shown below.
There is also a --warningyesnocancel variation, as shown below.
Example 15. --warningyesnocancel message box
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \ "About to exit.\n Do you want to save the file first?" |
A Yes/No/Cancel warning message box is shown below.
The return value ($?) from all these dialog boxes follows a common pattern. A Yes, OK or Continue returns zero. A No returns one. A Cancel returns two.
User Input dialogs
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 16. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to use" |
An input dialog box is shown below.
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 17. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to use" "default Name" |
An input dialog box with initial default text is shown below.
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
Displaying files
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Menu and selection dialogs
This section covers simple menus, checklists and radio buttons. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 20. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English" |
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 21. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \ 2 French on 3 "Oz' English" off |
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 22. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \ 2 French on 3 "Oz' English" off "1" "2" "3" $ kdialog --separate-output --checklist "Select languages:" \ 1 "American English" off 2 French on 3 "Oz' English" off 1 2 3 |
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 23. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \ English" off 2 French on 3 "Oz' English" off |
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
File selection dialogs
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 25. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename . /home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am [bradh@rachel kdialog]$ kdialog --getopenurl . file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am |
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 26. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1 kdialog --getopenfilename :label1 |
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 27. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain" |
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 28. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files" |
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 30. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files" |
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.