# gdialog Manual

2001
Patanjali Somayaji
2002, 2003
John Fleck
GNOME Documentation Project

&legal;

This is version 2.0 of the GDialog manual.

## Feedback Information

To report a bug or make a suggestion regarding this application or this documentation, please see the GNOME Feedback Page.

Patanjali
Somayaji
GNOME Documentation Project
John
Fleck
GNOME Documentation Project
1.0
25 Aug. 2001

Patanjali Somayaji

GNOME Documentation Project

2.0
7 April 2002

John Fleck jfleck@inkstain.net

GNOME Documentation Project

GNOME 2 version

2.2
14 January 2003

John Fleck jfleck@inkstain.net

GNOME Documentation Project

GNOME 2 version

## Introduction

&app; displays GNOME dialogs from the command line or in shell scripts.

&app; is included in the `gnome-utils` package, which is part of the GNOME desktop environment. This document describes version &version; of gdialog.

## Using gdialog

### Basic usage

A series of command line options appended to `gdialog` control dialog to be created. For example,

    	gdialog --msgbox "Test message" 200 150

creates and displays the dialog box shown in . The option `--msgbox` describes the type of dialog to be created. `"Test message"` provides the message. The numbers that follow specify the dialog's height and width.

#### gdialog example

gdialog msgbox example

The complete &app; command line options list is:

`gdialog [--title title] [--separate-output] [--backtitle backtitle] [--clear] Box options`

`title` specifies the title for the dialog.

"Box Options" can be one of the following:

- `[--defaultno] --yesno text height width`

- `--msgbox text height width`

- `--infobox text height width`

- `--inputbox text height width [init]`

- `--textbox file height width`

- `--menu text height width menu height tag1 item1 ...`

- `--checklist text height width list height tag1 item1 status1 ...`

- `--radiolist text height width list height tag1 item1 status1 ...`

- `--gauge text height width percent`

In the current implementation of &app;, a height and width must be specified, but they have no effect. This is a known bug.

## Using different types of dialog boxes

### Confirmation Dialog — A Yes/No Box

To create a dialog box showing a question and a "Yes" and a "No" button, use the `--yesno` option. To create a dialog box with the title as "My Dialog", and question to be shown "Should I exit ?" use the following command:

    	gdialog --title "My Dialog" --yesno "Should I exit ?" 250 150

The above command displays the dialog box shown in figure .

#### Confirmation Box Example

gdialog confirmation box example

The following script shows a "Yes/No" dialog and responds based on the input provided:

    #!/bin/sh
    if gdialog --title "Yes/No Test" --yesno "Yes No Test" 300 300
        then echo "You clicked yes."
        else echo "You clicked no."
    fi

By default, the "Yes" button is highlighted when the dialog is displayed. To highlight "No", add `--defaultno`:

    gdialog --title "test" --yesno "test" 1 1 --defaultno

### Message Box

Create a dialog box that shows a message with the `--msgbox` option:

    	gdialog --title "My Dialog" --msgbox "Here's a message" 250 150

This displays the dialog box shown in figure .

#### Message box example

gdialog message box example

### Infobox

The `--infobox` option creates a box identical to a `--msgbox` but leaves it on the screen only temporarily before it destroys itself.

### Inputting Text — Inputbox

Use `--inputbox` to display a text input box. The following script displays the input text. It responds with an error message if the Cancel button is clicked:

    #!/bin/sh

    if gdialog --title "An Input Box" \
            --inputbox "This box accepts a message." 20 20
        then echo $?
    else echo "No text input."
    fi

### Text Box

&app; can display a text file in a window using the `--textbox` option:

    gdialog --title "textbox" --textbox "gdialog.xml" 30 50

If the file is successfully displayed, &app; returns the value `TRUE` to your shell script. If the file does not exist, &app; will display an error dialogue and return the value `FALSE` to your shell script.

### Menu

The `--menu` option creates a menu and returns a value selected by the user. Each menu option includes two values, a `tag` and an `item`. &app; returns the value of the selected `tag`, as demonstrated in the following script:

    #!/bin/sh

    if gdialog --title "A Menu" \
            --menu "This is a menu of options." 100 200 1 \
        "One" "First menu item" \
        "Two" "Second menu item" \
        "Three" "Third menu item" \
        "Four" "Fourth menu item" \
        "Five" "Fifth menu item"
        then echo $?
    else echo "No selection made."
    fi

If a menu item is chosen, &app; returns `TRUE`. If the user clicks Cancel the script returns `FALSE.`

FIXME - the height and width bits seem to do nothing here

### Checklist

The `--checklist` option creates a checklist and returns the selected values. Each checklist option includes three values:

- A `tag`;

- A descriptive `item` to display in the dialog;

- A `status`, which must be either `on` or `off`. It determines whether the check box is checked or unchecked by default.

All selected `tag` values are returned, as demonstrated in the following script:

    #!/bin/sh

    if gdialog --title "A Checkllist" \
            --checklist "This is a checklist of options." 300 300 100 \
        "One" "First menu item" off \
        "Two" "Second menu item" on \
        "Three" "Third menu item" on \
        "Four" "Fourth menu item" on \
        "Five" "Fifth menu item" on
        then echo $@
    else echo "No selection made."
    fi

### Radio List

The `--radiolist` creates a list of options, only one of which can be selected. `--radiolist` uses the same syntax as the `--checklist`, except that only a single item can be given the `status` of `on` by default. If more than one item is set `on`, &app; selects the last one chosen as its default.

### Gauge

The `--gauge` option creates a progress bar. In addition to the normal height and width parameters, a final parameter indicating the percentage of progress is displayed. In this example:

    gdialog --title "Gauge" --gauge "This is a gauge" 100 100 20

Changing values for the progress bar can be fed to &app; from STDIN, as follows:

    #!/bin/sh

    (
    echo "10" ; sleep 1
    echo "20" ; sleep 1
    echo "50" ; sleep 1
    echo "75" ; sleep 1
    echo "100" ; sleep 1
    ) |
    gdialog --title "GAUGE" --gauge "This is a gauge widget" 10 10 0

## Authors

gdialog was written by Savio Lam (lam836@cs.cuhk.hk) and Stuart Herbert (S.Herbert@shef.ac.uk). Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. You can also use Bug Report Tool (`bug-buddy`), available in the Utilities submenu of Main Menu, for submitting bug reports.

This manual was written by Patanjali Somayaji (patanjali@morelinux.com) and John Fleck (jfleck@inkstain.net) Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs@gnome.org.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        59 Temple Place - Suite 330
        Boston, MA 02111-1307
        USA