Xdialog(1)

📦 version 2.3.1, in fedora 43, fedora 44

🎀 Xdialog(1): X11/tool manual 🎀

✨ NAME ✨

Xdialog - (c)dialog replacement for X-Windows 💖

✨ SYNTAX ✨

Xdialog [<common options>] [<transient options>] <box option> ...

and:

Xdialog <special option>

🌈 DESCRIPTION 🌈

Okay so Xdialog is designed to be a drop-in replacement for the dialog and cdialog programs 💅 (BTW Xdialog may also be used in place of gdialog, iykyk). It takes any terminal-based program and gives it a full glow-up into an X-windows interface 🦋. The dialogs are easier to see and use, and the new widgets add even more functionality ✨. It's giving upgrade, no cap.

To pull this off, Xdialog uses the Gimp ToolKit (also known as GTK+) 🛠️. Lowkey, that's the engine behind the whole glow-up 🫶.

👑 OPTIONS 👑

The [<common options>] [<transient options>] <box option> sequence can be repeated several times in the same Xdialog command line. This is called dialog chaining 🔗. The common and transient options are optional, but there must always be a box option as the last Xdialog option, bestie 💜.

🌸 Common options 🌸

The <common options> are the ones that hang over every following <box options> until you hit the same or opposite <common options> on the command line. They're mostly about menu look, style, placement and behaviour, so basically the whole aesthetic 💅.

Here's the full list, bestie:

  • --wmclass <name> — takes a name 🏷️
  • --rc-file <gtkrc filename> — takes a gtkrc filename 📄
  • --backtitle <backtitle> — takes a backtitle 🎀
  • --title <title> — takes a title 🌷
  • --allow-close | --no-close — pick one: allow close or no close 🚪
  • --screen-center | --under-mouse | --auto-placement — three placement vibes, pick one 📍
  • --center | --right | --left | --fill — four layout options, pick one ✨
  • --no-wrap | --wrap — wrap or no wrap 🌀
  • --cr-wrap | --no-cr-wrap — another wrap pair, pick one 🔁
  • --stderr | --stdout — choose where the results go, stderr or stdout 📬 (more on that in DIAGNOSTICS 👀)
  • --separator <character> | --separate-output — takes a character ✂️, or use the separate-output one instead
  • --buttons-style default|icon|text — pick a button style: default, icon or text 🔘

🧁 Transient options 🧁

The <transient options> only apply to the next <box option> on the command line. These are for tuning the widgets (number and type of buttons, menu icon) or triggering some of the widgets' specific features 🎀.

Available transient options:

  • --fixed-font — for use with --tailbox, --textbox and --editbox 🔤
  • --password | --password=1|2 — this one may be repeated 2 or 3 times before --2inputsbox or --3inputsbox 🔐. You can also specify one (and only one) password field with the --password=1|2 syntax.
  • --editable — for use with --combobox ✏️
  • --time-stamp | --date-stamp — for use with --logbox ⏰
  • --reverse — for use with --logbox 🔄
  • --keep-colors — for use with --logbox 🌈
  • --interval <timeout> — may be used with input(s) boxes, combo box, range(s) boxes, spin(s) boxes, list boxes, menu box, treeview, calendar and timebox widgets 🫧
  • --timeout <timeout> (in seconds) — may be used with all but infobox, gauge and progress widgets ⏳
  • --no-tags — for use with --menubox, --checklist and --radiolist 🙈
  • --item-help — when you use this, the <helpN> parameters of --menubox, --checklist, --radiolist, --buildlist and --treeview must be specified. If --item-help is not specified, they must be omitted 🧩
  • --default-item <tag> — for use with --menubox 🎯
  • --icon <xpm filename> — for use with any widget accepting a <text> parameter 🖼️
  • --no-ok — for use with --tailbox and --logbox 🙅
  • --no-cancel — may be used with all but --infobox, --gauge and --progress ❌
  • --no-buttons — may be used with --textbox, --tailbox, --logbox, --infobox, --fselect and --dselect 🫥
  • --default-no — may be used with all widgets with a "Cancel" or "No" button. Note that it's ignored when the --wizard option is in force 🙃
  • --wizard — may be used with all but --msgbox, --infobox, --gauge and --progress 🧙
  • --help <help> — may be used with all but --infobox, --gauge and --progress 🆘
  • --print <printer> — for use with --tailbox, --textbox and --editbox 🖨️
  • --check <label> [<status>] — may be used with all but --infobox, --gauge and --progress ☑️
  • --ok-label <label> — may be used with all widgets with an "OK" or "Yes" button. Note that it's ignored when the --wizard option is in force 🥳
  • --cancel-label <label> — may be used with all widgets with a "Cancel" or "No" button. Note that it's ignored when the --wizard option is in force 🏳️
  • --beep — may be used with all widgets 🔔
  • --beep-after — may be used with all widgets 🔕
  • --begin <Yorg> <Xorg> — may be used with all widgets 📐
  • --ignore-eof — may be used with --infobox and --gauge 🫠
  • --smooth — for use with --tailbox and --logbox 🧈

💖 Box options 💖

The <box option> tells Xdialog which widget to show, and it's followed by three or more parameters:

  • the first parameter is a text string or a filename (this depends on the box option) 📝
  • the second and third parameters are menu <height> and <width> in characters. These two can be swapped out for a single <XSIZExYSIZE> parameter, which gives the width and height in pixels 📏
    • when a size of 0 0 (or 0x0) is passed to Xdialog, the widget is auto-sized by GTK+ 🪄
    • when a size of -1 -1 (or -1x-1) is passed, the Xdialog widget is set to the maximum size so it fits the screen 🖥️
    • you can give the widget an absolute origin on the screen (provided your window manager lets you do so), either with the --begin transient option (when the size is given in characters) or with a "-geometry"-like origin, e.g. 400x200+20-30 📍
  • some box options need extra parameters such as tags, menu items, labels or default values 🏷️

Available box options:

  • --yesno <text> <height> <width> — the yes/no box, the classic 🤷
  • --msgbox <text> <height> <width> — message box 📣
  • --infobox <text> <height> <width> [<timeout>] — info box ℹ️, with an optional timeout
  • --gauge <text> <height> <width> [<percent>] — gauge with an optional percent 📊
  • --progress <text> <height> <width> [<maxdots> [[-]<msglen>]] — progress box with dots 🐾
  • --inputbox <text> <height> <width> [<init>] — text input box ⌨️, with an optional initial value
  • --2inputsbox <text> <height> <width> <label1> <init1> <label2> <init2> — two input fields 👯
  • --3inputsbox <text> <height> <width> <label1> <init1> <label2> <init2> <label3> <init3> — three input fields 🫂
  • --combobox <text> <height> <width> <item1> ... <itemN> — combo box 🍓
  • --rangebox <text> <height> <width> <min value> <max value> [<default value>] — range box 🎚️
  • --2rangesbox <text> <height> <width> <label1> <min1> <max1> <def1> <label2> <min2> <max2> <def2> — two range boxes in one 🎚️🎚️
  • --3rangesbox <text> <height> <width> <label1> <min1> <max1> <def1> <label2> <min2> <max2> <def2> <label3> <min3> <max3> <def3> — three ranges, the whole set 🌈
  • --spinbox <text> <height> <width> <min> <max> <def> <label> — spin box 🌀
  • --2spinsbox <text> <height> <width> <min1> <max1> <def1> <label1> <min2> <max2> <def2> <label2> — two spin boxes 🌀🌀
  • --3spinsbox <text> <height> <width> <min1> <max1> <def1> <label1> <min2> <max2> <def2> <label2> <min3> <max3> <def3> <label3> — three spin boxes, triple the spin 🌪️
  • --textbox <file> <height> <width> — text box for reading a file 📖
  • --editbox <file> <height> <width> — edit box for a file ✍️
  • --tailbox <file> <height> <width> — tail box for a file 📜
  • --logbox <file> <height> <width> — log box 🗒️
  • --menubox <text> <height> <width> <menu height> <tag1> <item1> {<help1>}... — menu box 🍔
  • --checklist <text> <height> <width> <list height> <tag1> <item1> <status1> {<help1>}... — checklist ✅
  • --radiolist <text> <height> <width> <list height> <tag1> <item1> <status1> {<help1>}... — radio list 🔘
  • --buildlist <text> <height> <width> <list height> <tag1> <item1> <status1> {<help1>}... — build list 🧱
  • --treeview <text> <height> <width> <list height> <tag1> <item1> <status1> <item_depth1> {<help1>}... — treeview 🌳
  • --fselect <file> <height> <width> — file selector 📁
  • --dselect <directory> <height> <width> — directory selector 🗂️
  • --colorsel <text> <height> <width> [<red> <green> <blue>] — colour picker 🎨
  • --fontsel <font name> <height> <width> — font picker 🔤
  • --calendar <text> <height> <width> [<day> <month> <year>] — calendar 📅
  • --timebox <text> <height> <width> [<hours> <minutes> <seconds>] — time box ⏰

🪄 Special options 🪄

The <special options> take no parameter and need to be used alone on the command line. They just print a string to stderr and exit immediately with a 0 exit code 🫶.

Available special options:

  • --version — prints the version number to stderr and exits 🔢
  • --print-version — same as above, but in a cdialog-compatible way 🧃
  • --print-maxsize — prints the maximum menu size in characters and exits 📐

✨ ENVIRONMENT VARIABLES ✨

okay bestie, this section is where you get to flip Xdialog into a totally different mode 💅🌸

XDIALOG_HIGH_DIALOG_COMPAT

so if you set this to 1 or true (case doesn't matter, we're not gatekeeping 🫶), you turn on the (c)dialog high compatibility mode 🦋 and honestly the glow-up is real. Here's what changes:

  • everything uses a fixed (monospacing) font 🎀, including labels, tags, menu/list items, and buttons. no cap, it's giving typewriter energy ⌨️
  • the --left common option becomes the default justification instead of --center 🍓
  • <text> wrapping is always on (that's --wrap) and the --fill option gets ignored, so don't even bother 🙈
  • the --no-cr-wrap common option becomes the default instead of --cr-wrap 💜 (but it does NOT apply to the <backtitle>, so that one's still doing its own thing 🧚)
  • the auto-sizing feature gets forced no matter what box size you asked for, but only if you also set XDIALOG_FORCE_AUTOSIZE to 1 or true ✨ this is the fix for menus that are lowkey too cramped, like when your box is too small to fit all the menu/list entries you gave it 😭
  • the Cancel button disappears from the tailbox and textbox widgets 💀
  • the infobox widget turns into a msgbox unless XDIALOG_INFOBOX_TIMEOUT is set (in 1/1000s) and greater than 0. in that case you get a real infobox with no button 🌈
  • the --version special option returns the same string as --print-version 👑

XDIALOG_FORCE_AUTOSIZE

XDIALOG_INFOBOX_TIMEOUT

these two are part of the XDIALOG_HIGH_DIALOG_COMPAT glow-up, so check the notes above for the full tea ☕💖

XDIALOG_NO_GMSGS

if you set this to 1, the Gdk, GLib, and Gtk libraries stop emitting messages through g_log() 🤫🫶 quiet vibes only

✨ EXAMPLES ✨

sample scripts live in the /usr/share/doc/xdialog-2.3.1/samples/ directory 📂🧚

and the full HTML doc, with screen shots, examples, and FAQ, is in the /usr/share/doc/xdialog-2.3.1/ directory 📸🦋

✨ AUTHORS ✨

  • Thierry Godefroy <xdialog@free.fr> — the queen, from v1.1.0 onwards 👑💅
  • Alfred Reynolds <alfred@cyberone.com.au> — the OG, v1.0 only 🌸

✨ SEE ALSO ✨

  • dialog(1), cdialog(1) — the besties you should go check out next 🫶💖

Thierry Godefroy, version 2.3.1, Xdialog(1) 🎀 that's the whole page, bestie. you're officially dialog-brained now 🌈💜

📦 where this page comes from