KDialog - Scott Ferguson - IT Consulting

Using KDialog

KDialog can be used to show nice dialog boxes from shell scripts. In Debian(external link) it's part of the kde-baseapps-bin package, which provides core binaries for the KDE(external link) base applications.

A nice guide to the basic use of KDialog(external link) can be found at KDE TechBase(external link), unfortunately it doesn't cover all the capabilities of KDialog. This page attempts to show some of the undocumented and less well known capabilities of KDialog.
Another good site for information about KDialog is Little Girl's Mostly Linux Blog(external link), while it hasn't been updated for a while, I've recently corresponded with the author and I expect she'll add more information soon.


Usage: kdialog [Qt-options] [KDE-options] [options] [arg]

Generic options:

--help Show help about options
--help-qt Show Qt specific options
--help-kde Show KDE specific options
--help-all Show all options
--author Show author information
-v, --version Show version information
--license Show license information
-- End of options

Qt options:

--display <displayname> Use the X-server display displayname
--session <sessionId> Restore the application for the given sessionId
--cmap Causes the application to install a private color map on an 8-bit display
--ncols <count> Limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification
--nograb tells Qt to never grab the mouse or the keyboard
--dograb running under a debugger can cause an implicit -nograb, use -dograb to override
--sync switches to synchronous mode for debugging
--fn, --font <fontname> defines the application font
--bg, --background <color> sets the default background color and an application palette (light and dark shades are calculated)
--fg, --foreground <color> sets the default foreground color
--btn, --button <color> sets the default button color
--name <name> sets the application name
--title <title> sets the application title (caption)
--testability load the testability framework
--visual TrueColor forces the application to use a TrueColor visual on an 8-bit display
--inputstyle <inputstyle> sets XIM (X Input Method) input style. Possible values are onthespot, overthespot, offthespot and root
--im <XIM server> set XIM server
--noxim disable XIM
--reverse mirrors the whole layout of widgets
--stylesheet <file.qss> applies the Qt stylesheet to the application widgets
--graphicssystem <system> use a different graphics system instead of the default one, options are raster and opengl (experimental)
--qmljsdebugger <port> QML JS debugger information. Application must be built with -DQT_DECLARATIVE_DEBUG for the debugger to be enabled

KDE options:

--caption <caption>
Use caption as name in the titlebar
--icon <icon>
Use icon as the application icon
--config <filename>
Use alternative configuration file
Disable crash handler, to get core dumps
Waits for a WM_NET compatible windowmanager
--style <style> sets the application GUI style
--geometry <geometry> sets the client geometry of the main widget - see man X for the argument format (usually WidthxHeight+XPos+YPos)

The return value ($?) from these dialog boxes is:-

  • Yes, OK or Continue returns 0
  • No returns 1
  • Cancel returns 2

Undocumented Options

In most instances the dialogs will allow a subset of HTML with <text>
Valid tags are <hn>, <p>, <hr />, <p>, <img>, <ul>, <ol>, <b>, <i>, and <u>
In some instances <a> will render but not launch a browser or email client (i.e. an image can be fetched, and sometimes an option to copy the link will show as a right-click option).

Example:-Picture of the Kdialog error dialog using undocumented options to display HTML


--yesno <text>Question message box with yes/no buttons
Picture of yesno Kdialog

--geometry does not work

--yesnocancel <text>Question message box with yes/no/cancel buttons
Picture of yesnocancel Kdialog
--warningyesno <text>Warning message box with yes/no buttons
Picture of warningyesno Kdialog
--warningcontinuecancel <text>Warning message box with continue/cancel buttons
Picture of warningcontinuecancel Kdialog
--warningyesnocancel <text>Warning message box with yes/no/cancel buttons
Picture of warningyesnocancel Kdialog
--yes-label <text>Use text as Yes button label
kdialog --warningyesnocancel "Porta dignissim senectus nibh dignissim odio conubia ve, dui ve eros." --yes-label "Lorem"
Picture of yes-label Kdialog
--no-label <text>Use text as No button label
Picture of use alternative text for the no button on a Kdialog
--cancel-label <text>Use text as Cancel button label
Picture of using alternative text for the Cancel button on a Kdialog
--continue-label <text>Use text as Continue button label
Picture of using alternative text for the Continue button on a Kdialog
--sorry <text>'Sorry' message box
Picture of the Sorry Kdialog
--detailedsorry <text> <details>'Sorry' message box with expandable Details field
A subset of HTML can be used in both the <text> and the <details>
Picture of using the Sorry Kdialog with expandable details
--error <text>'Error' message box
Picture of using the Error Kdialog
--detailederror <text> <details>'Error' message box with expandable Details field
A subset of HTML can be used in both the <text> and the <details>
Picture of using the Error Kdialog with expandable details
--msgbox <text>Message Box dialog
Picture of using Message Kdialog
--inputbox <text> <init>Input Box dialog
Returns <init> text
kdialog --inputbox "Nunc fringilla faucibus, fames a nibh etiam eu habitasse nisi." "Interesting, init?"
Interesting, init?
Picture of using the Kdialog Input box
--password <text>Password dialog
Returns password
Picture of using the Password Kdialog
--textbox <file> [width] [height]Text Box dialog
kdialog --textbox ~/textbox.txt 360 280
Note: Limited support for HTML. Links and divs don't work.
Picture of using the Text Box Kdialog
--textinputbox <text> <init> [width] [height]Text Input Box dialog
Returns the text from the input box
kdialog --textinputbox "<h1>Messagebox text</h1><p>Cum, tempor vehicula <b>mus</b> eget venenatis suscipit tellus nostra.</p><p><a href='http://scottferguson.com.au'><img src='main_logo.png'></a></p>" "Nice day init" 380 280
Note that the <html></html> tags haven't been used Picture of using the Textinput Kdialog
--combobox <text> item [item] [item] ...ComboBox dialog
Returns selected item
Note use of (\n) new line
kdialog --combobox "In imperdiet etiam ridiculus convallis\nfelis a feugiat semper, convallis vestibulum mus\nvestibulum mauris, vel, pharetra." "Testicles" "Wallet" "Watch" "Glasses"
Picture of using the ComboBox Kdialog
Another picture of using the ComboBox Kdialog
--menu <text> [tag item] [tag item] ...Menu dialog
'kdialog --menu "Cum morbi massa, cubilia at." "Et masa" Convrturient "vestibulum mauris" Cras "Sit netus ligula enim potenti donec arcu tr donec, eu etiam mollis consequat" Ante "Morbi purus tortor libero augue ipsquam" Pretium
vestibulum mauris
Yes another picture of using the ComboBox Kdialog
--menu <text> [tag item] [tag item] ...Menu dialog
'kdialog --menu "Cum morbi massa, cubilia at." "Et masa" Convrturient "vestibulum mauris" Cras "Sit netus ligula enim potenti donec arcu tr donec, eu etiam mollis consequat" Ante "Morbi purus tortor libero augue ipsquam" Pretium
vestibulum mauris
Still yet another picture of using the ComboBox Kdialog
--checklist <text> [tag item status] ...Check List dialog
Returns 0 for OK (if the default is used, status on), 1 for Cancel, otherwise it returns the number/s of the item/s (in parenthesis)
kdialog --checklist "<h1>Search engines and motors</h1><p><h4>Choose one</h4><hr />" 1 "Rutrum ante" off 2 "Velit" off 3 "Aenean ante" off 4 "Integer eni" On
Picture of using the Checklist Kdialog
--radiolist <text> [tag item status] ...Radio List dialog
the same as --checklist except that only a single item can be selected
--passivepopup <text> <timeout>Passive Popup
kdialog --passivepopup "<h4>HTML <i>sort</i> of works</h4><br /><img src='/home/scott/main_logo.png' height='58' width='150'><hr />" 10
Picture of using the passivepopup Kdialog
--getopenfilename [startDir] [filter]File dialog to open an existing file
Returns full path to selected file
kdialog --getopenfilename '~/Projects/Business Manual/dokuwiki backup' '*.png'
Picture of using the GetOpenFileName Kdialog
--getsavefilename [startDir] [filter]File dialog to save a file
Returns full path to save file
kdialog --getsavefilename '~/Projects/Business Manual/dokuwiki backup' '*.png'
e.g. /home/scott/Projects/Business Manual/dokuwiki backup/test.png
Picture of using the GetSaveFileName Kdialog
--getexistingdirectory [startDir]File dialog to select an existing directory
--getopenurl [startDir] [filter]File dialog to open an existing URL
--getsaveurl [startDir] [filter]File dialog to save a URL
--geticon [group] [context]Icon chooser dialog
--progressbar <text> [totalsteps]Progress bar dialog, returns a D-Bus reference for communication
--getcolorColor dialog to select a color
--title <text>Dialog title
--default <text>Default entry to use for combobox, menu and color
--multipleAllows the --getopenurl and --getopenfilename options to return multiple files
--separate-outputReturn list items on separate lines (for checklist option and file open with -- multiple)
--print-winidOutputs the winId of each dialog
--dontagain <file:entry>Config file and option name for saving the “do-not-show/ask-again” state
--slider <text> [minvalue] [maxvalue] [step]Slider dialog box, returns selected value
--calendar <text>Calendar dialog box, returns selected date
--attach <winid>Makes the dialog transient for an X app specified by winid


arg Arguments - depending on main option

Send message to remote KDE machine

ssh-copy-id only needs to be run once, but causes no problems run multiple times

echo $PASSWORD | ssh-copy-id '$USER@$USER_IP_ADDRESS -c blowfish' ssh -c blowfish $USER@$USER_IP_ADDRESS 'export DISPLAY=:0 &&\ kdialog --msgbox "Please call Scott\n\n \ Your computer needs:-\n a backup\n an upgrade applied\n" &'

Special characters in menus

kdialog --menu 'Pick one action to display, or two to win a prize!' -- \ "-vcodec mpeg2 stuff -ab 1000k" MPEG\ "avi -vcodec avi stuff -ab 1000k" AVI\ "mp3 -acodec mp3 stuff -ab 128k" MP4\ "*we're* %special& \yeah" 'Special Characters'\ mpeg -vcodec mpeg2 stuff -ab 1000k

Returns the text of the selected item e.g. *we're* %special& \yeah Picture of using special characters in the Menu Kdialog

Progress bar

dbusRef=`kdialog --progressbar "Press Cancel at Any time" 10` qdbus $dbusRef showCancelButton true until test "true" = `qdbus $dbusRef wasCancelled`; do sleep 1 inc=$((`qdbus $dbusRef Get "" "value"` + 1)) qdbus $dbusRef Set "" "value" $inc; done qdbus $dbusRef close

Remote Server Status

Picture of using Kdialog with a Bash script

Runs at end of boot

$ cat /etc/rc.local

#!/bin/sh -e # # rc.local # # This script is executed at the end of each multiuser runlevel. # Make sure that the script will "exit 0" on success or any other # value on error. # # In order to enable or disable this script just change the execution # bits. # # By default this script does nothing. #/home/scott/beep.sh ssh scott@work 'export DISPLAY=:0 && kdialog --icon network-server --title "Remote Server"\ --caption "Status" --msgbox "The Development Server is ready" & \ echo "tha development server is red-e" | festival --tts' exit 0

Adding icons to Kdialog

Choose an icon then note it's name

kdialog --geticon app kdialog --geticon [group] [context]


Display passive popup


kdialog --icon 'edit-undo' --title 'PIM backup' --passivepopup 'backed up $home/GNUCash' 5

Another picture of a PassivePopup Kdialog

–icon is a KDE parameter.

Pick from a list and initiate an action Lightweight VirtualBox Machine launcher for use across a network

Display icons


kdialog --geticon all all

Picture of using Kdialog to select a system icon

Questions or comments? Email them to me using the link in the footer.

Picture of the KDE logo, a large white letter K over a white gear wheel on a blue background

KDE is an international free software community producing an integrated set of cross-platform applications designed to run on modern Unix-like and Microsoft Windows systems. It is known for its Plasma Desktop, a desktop environment which is provided as the default work environment on many Linux distributions, such as openSUSE, Mageia, and Kubuntu. It is also the default desktop environment on PC-BSD, a BSD operating system.

The goal of the community is to provide basic desktop functions and applications for daily needs of an end-user as well as tools and documentation for developers to write stand-alone applications for the system. In this regard, the KDE project serves as an umbrella project for many standalone applications and smaller projects that are based on KDE technology. These include Calligra Suite, digiKam, and many others.

KDE software is based on the Qt framework. The original GPL version of this toolkit only existed for the X11 platform, but with the release of Qt 4, LGPL versions are available for all platforms. This allows KDE software based on Qt 4 to also be distributed to Microsoft Windows and OS X.

A Debian logoDebian supports the Linux, kfreeBSD, and Hurd kernels, 10 different processor architectures, and over 20,000 software packages.
If you've ever seen Ubuntu or Mint then you've seen repackaged Debian (this webserver runs pure Debian).