# MateDialogn ohje

## Johdanto

MateDialog mahdollistaa seuraavan tyyppisten yksinkertaisten ikkunoiden luomisen:

- Kalenteri

- Tiedoston valinta

- Luettelo

- Ilmoituskuvake

- Viesti

  - Virhe

  - Tiedoksi

  - Kysymys

  - Varoitus

- Edistyminen

- Tekstisyöte

- Tekstihuomatus

## Käyttö

Skriptejä kirjoitettaessa voi MateDialogä käyttää yksinkertaisten valintaikkunoiden luomiseen, jotka pyytävät käyttäjältä syötettä graafisesti, kuten seuraavissa tapauksissa:

- Voit luoda valintaikkunan keräämään tietoa käyttäjältä. Voit esimerkiksi pyytää käyttäjää valitsemaan päivän kalenteri-ikkunasta tai valitsemaan tiedoston tiedoston valintaikkunalla.

- Voit luoda ikkunan, joka kertoo käyttäjälle tietoa. Voit esimerkiksi näyttää edistymisikkunassa operaation edistymisen tilanteen tai varoitusviesti-ikkunassa varoittaa käyttäjää.

Kun käyttäjä sulkee ikkunan, MateDialog tulostaa ikkunaan syötetyn tekstin vakiotulosteeseen.

Kun kirjoitat MateDialog-komentoja, ole tarkkana lainausmerkkien sijoittelussa jokaisen argumentin ympärillä.

For example, use:

    matedialog --calendar --title="Holiday Planner"

Do not use:

    matedialog --calendar --title=Holiday Planner

Mikäli et käytä lainausmerkkejä, saatat saada odottamattomia tuloksia.

### Valintanäppäimet

Valintanäppäin on näppäin, joka antaa mahdollisuuden suorittaa toiminto näppäimistöltä sen sijaan, että komento valittaisiin hiirellä valikosta tai ikkunasta. Jokainen valintanäppäin identifioidaan alleviivaamalla kirjain valikossa tai ikkunan kohdassa.

Jotkut MateDialog-ikkunan tukevat valintanäppäinten käyttöä. Määrittääksesi kirjaimen valintanäppäimeksi, anna alaviiva ennen kirjainta ikkunan tekstissä. Seuraava esimerkki valaisee kuinka kirjain "V" määritetään valintanäppäimeksi:

    "_Choose a name".

### Päättymiskoodit

MateDialog palauttaa seuraavia päättymiskoodeja:

Päättymiskoodi | Kuvaus
`0` | Käyttäjä painoi joko OK tai Sulje.
`1` | Käyttäjä painoi Peru tai käytti ikkunapainikkeita sulkemaan valintaikkunan.
`-1` | Tapahtui odottamaton virhe.
`5` | Ikkuna suljettiin aikarajan päätyttyä.

### Yleiset valitsimet

Kaikki MateDialog-ikkunat tukevat seuraavia yleisiä valitsimia:

`--title`=`otsikko`

- Määrittää ikkunan otsikon.

`--window-icon`=`kuvakepolku`

- Määrittää kuvakkeen, joka näytetään ikkunan kehyksessä. Saatavilla on myös neljä valmista kuvaketta, jotka saa käyttöön seuraavilla avainsanoilla - "info" (tietoa), "warning" (varoitus), "question" (kysymys) ja "error" (virhe).

`--width`=`leveys`

- Määrittää ikkunan leveyden.

`--height`=`korkeus`

- Määrittää ikkunan korkeuden.

`--timeout`=`aikaraja`

- Määrittää aikarajan sekunteina, jonka jälkeen ikkuna suljetaan.

### Ohjevalitsimet

MateDialog tarjoaa seuraavat ohjevalitsimet:

`--help`

- Näyttää lyhennetyn ohjetekstin.

`--help-all`

- Näyttää täyden ohjetekstin kaikista ikkunatyypeistä.

`--help-general`

- Näyttää ohjetekstin yleisistä ikkunavalitsimista.

`--help-calendar`

- Näyttää ohjetekstin kalenteri-ikkunan valitsimista.

`--help-entry`

- Näyttää ohjetekstin tekstisyöttöikkunan valitsimista.

`--help-error`

- Näyttää ohjetekstin virheikkunan valitsimista.

`--help-info`

- Näyttää ohjetekstin tietoikkunan valitsimista.

`--help-file-selection`

- Näyttää ohjetekstin tiedoston valintaikkunan valitsimista.

`--help-list`

- Näyttää ohjetekstin luetteloikkunan valitsimista.

`--help-notification`

- Näyttää ohjetekstin ilmoituskuvakkeiden valitsimista.

`--help-progress`

- Näyttää ohjetekstin edistymisikkunan valitsimista.

`--help-question`

- Näyttää ohjetekstin kysymysikkunan valitsimista.

`--help-warning`

- Näyttää ohjetekstin varoitusikkunan valitsimista.

`--help-text-info`

- Näyttää ohjeen tietoikkunan valitsimista.

`--help-misc`

- Näyttää ohjeen sekalaisista valitsimista.

`--help-gtk`

- Näyttää ohjeen GTK+-valitsimista.

### Sekalaisia valitsimia

MateDialogllä on myös seuraavat sekalaiset valitsimet:

`--about`

- Näyttää Tietoja MateDialogstä -ikkunan, joka sisältää tiedot MateDialogn versiosta, tekijänoikeuksista ja kehittäjistä.

`--version`

- Näyttää MateDialogn versionumeron.

### GTK+-valitsimet

MateDialog tarjoaa tavanomaiset GTK+-valitsimet. Lisätietoa GTK+-valitsimista saa komennolla `matedialog -?`.

### Ympäristömuuttujat

Normaalisti MateDialog tunnistaa pääteikkunan, josta se on käynnistetty ja pitää itsensä tämän ikkunan päällä. Tämä käytös voidaan estää poistamalla `WINDOWID`-ympäristömuuttuja.

## Kalenteri-ikkuna

Käytä valitsinta `--calendar` luomaan kalenteri-ikkuna. MateDialog palauttaa valitun päivämäärään vakiotulosteeseen. Mikäli päivämäärää ei määritetty komentorivillä, ikkuna avataan sen hetkisen päivän kohdalta.

Kalenteri-ikkuna tarjoaa seuraavat valitsimet:

`--text`=`teksti`

- Määrittää tekstin, joka näkyy kalenteri-ikkunassa.

`--day`=`päivä`

- Määrittää päivän, joka on aluksi valittuna kalenteri-ikkunassa. `päivä` tulee korvata numerolla 1—31.

`--month`=`kuukausi`

- Määrittää kuukauden, joka on aluksi valittuna kalenteri-ikkunassa. `kuukausi` tulee korvata numerolla 1—12.

`--year`=`vuosi`

- Määrittää vuoden, joka on aluksi valittuna kalenteri-ikkunassa.

`--date-format`=`muoto`

- Määrittää muotoilun, jossa kalenteri-ikkuna palauttaa päivämäärän valinnan jälkeen. Oletusmuotoilu riippuu maa-asetuksista. `muoto` täytyy koostua muotoilukoodeista, joita `strftime`-funktio hyväksyy, kuten `%A %Y-%m-%d`.

The following example script shows how to create a calendar dialog:

            #!/bin/sh

            if matedialog --calendar \
            --title="Select a Date" \
            --text="Click on a date to select that date." \
            --day=10 --month=8 --year=2004
              then echo $?
              else echo "No date selected"
            fi

### Esimerkki kalenteri-ikkunasta

MateDialog calendar dialog example

## Tiedoston valintaikkuna

Käytä valitsinta `--file-selection` luomaan tiedoston valintaikkuna. MateDialog palauttaa valitut tiedostot tai hakemistot vakiotulosteeseen. Oletusmoodi tiedoston valintaikkunalle on avaus.

Tiedoston valintaikkuna tarjoaa seuraavat valitsimet:

`--filename`=`tiedostonimi`

- Määrittää tiedoston tai hakemiston, joka on aluksi ikkunan tullessa näkyviin valittuna tiedoston valintaikkunassa.

`--multiple`

- Sallii valita kerralla useamman tiedoston tiedoston valintaikkunassa.

`--directory`

- Sallii vain hakemistojen valitsemisen tiedoston valintaikkunassa.

`--save`

- Asettaa tiedoston valintaikkunan tallennustilaan.

`--separator`=`erotin`

- Määrittää merkkijonon, jota käytetään erottamaan tiedostot palautettavassa tiedostonimien luettelossa.

The following example script shows how to create a file selection dialog:

            #!/bin/sh

            FILE=`matedialog --file-selection --title="Select a File"`

            case $? in
                     0)
                            echo "\"$FILE\" selected.";;
                     1)
                            echo "No file selected.";;
                    -1)
                            echo "No file selected.";;
            esac

### Esimerkki tiedoston valintaikkunasta

MateDialog file selection dialog example

## Ilmoituskuvake

`--text`=`teksti`

- Määrittää tekstin, joka näkyy ilmoitusalueella.

The following example script shows how to create a notification icon:

            #!/bin/sh

            matedialog --notification\
              --window-icon="info" \
              --text="There are system updates necessary!"

### Esimerkki ilmoituskuvakkeesta

MateDialog notification icon example

## Luetteloikkuna

Käytä valitsinta `--list` luomaan luetteloikkuna. MateDialog palauttaa valittujen rivien ensimmäisten sarakkeiden tiedot vakiotulosteeseen.

Ikkunan sisältö tulee määrittää sarake sarakkeelta ja rivi riviltä. Tiedot voidaan syöttää ikkunaan vakiosyötteen kautta. Jokainen tietue pitää erottaa rivinvaihtomerkillä.

Mikäli käytössä on valitsin `--checklist` tai `--radiolist`, jokaisen rivin tulee alkaa joko 'TRUE' (tosi) tai 'FALSE' (epätosi).

Luetteloikkuna tarjoaa seuraavat valitsimet:

`--column`=`sarake`

- Määrittää luetteloikkunassa näkyvien sarakkeiden otsakkeet. Määritä valitsin `--column` jokaiselle sarakkeelle, jonka haluat näkyvän ikkunassa.

`--checklist`

- Määrittää, että ensimmäinen sarake luetteloikkunassa sisältää valintaruutuja.

`--radiolist`

- Määrittää, että ensimmäinen sarake luetteloikkunassa sisältää radiovalitsimia.

`--editable`

- Sallii näytettävien tietuiden muokaamisen.

`--separator`=`erotin`

- Määrittää mitä merkkijonoa käytetään kun luetteloikkuna palauttaa valitut tietueet.

`--print-column`=`sarake`

- Määrittää mitkä sarakkeet tulostetaan valinnan jälkeen. Oletussarake on "1". "ALL" (kaikki) tarkoittaa, että kaikki luettelon sarakkeet tulostetaan.

The following example script shows how to create a list dialog:

            #!/bin/sh

            matedialog --list \
              --title="Choose the Bugs You Wish to View" \
              --column="Bug Number" --column="Severity" --column="Description" \
                992383 Normal "GtkTreeView crashes on multiple selections" \
                293823 High "MATE Dictionary does not handle proxy" \
                393823 Critical "Menu editing does not work in MATE 2.0"

### Esimerkki luetteloikkunasta

MateDialog list dialog example

## Viesti-ikkunat

MateDialog voi luoda neljän tyyppisia viesti-ikkunoita:

- Virhe

- Tiedoksi

- Kysymys

- Varoitus

Kaikille ikkunatyypeille valitsin `--text` määrittää ikkunassa näytettävän tekstin.

### Virheikkuna

Käytä valitsinta `--error` luomaan virheikkuna.

The following example script shows how to create an error dialog:

              #!/bin/bash

              matedialog --error \
              --text="Could not find /var/log/syslog."

#### Esimerkki virheikkunasta

MateDialog error dialog example

### Tietoikkuna

Käytä valitsinta `--info` luomaan tietoikkuna.

The following example script shows how to create an information dialog:

              #!/bin/bash

              matedialog --info \
              --text="Merge complete. Updated 3 of 10 files."

#### Esimerkki tietoikkunasta

MateDialog information dialog example

### Kysymysikkuna

Käytä valitsinta `--question` luomaan kysymysikkuna.

The following example script shows how to create a question dialog:

              #!/bin/bash

              matedialog --question \
              --text="Are you sure you wish to proceed?"

#### Esimerkki kysymysikkunasta

MateDialog question dialog example

### Varoitusikkuna

Käytä valitsinta `--warning` luomaan varoitusikkuna.

The following example script shows how to create a warning dialog:

              #!/bin/bash

              matedialog --warning \
              --text="Disconnect the power cable to avoid electrical shock."

#### Esimerkki varoitusikkunasta

MateDialog warning dialog example

## Edistymisikkuna

Käytä valitsinta `--progress` luomaan edistymisikkuna.

MateDialog lukee datan vakiosyötteestä rivi kerrallaan. Mikäli rivi alkaa #-merkillä, teksti päivitetään rivin tekstillä. Mikäli rivi sisältää vain numeron, edistymisprosentiksi päivitetään annettu numero.

Edistymisikkuna tarjoaa seuraavat valitsimet:

`--text`=`teksti`

- Määrittää tekstin, joka näytetään edistymisikkunassa.

`--percentage`=`prosentit`

- Määrittää prosentuaalisen osuuden alussa, joka asetetaan edistymisikkunaan.

`--auto-close`

- Edistymisikkuna suljetaan automaattisesti kun 100 % saavutetaan.

`--pulsate`

- Määrittää, että edistymisikkuna sykkii kunnes EOF-merkki (tiedoston loppumerkki) luetaan vakiosyötteestä.

The following example script shows how to create a progress dialog:

            #!/bin/sh
            (
            echo "10" ; sleep 1
            echo "# Updating mail logs" ; sleep 1
            echo "20" ; sleep 1
            echo "# Resetting cron jobs" ; sleep 1
            echo "50" ; sleep 1
            echo "This line will just be ignored" ; sleep 1
            echo "75" ; sleep 1
            echo "# Rebooting system" ; sleep 1
            echo "100" ; sleep 1
            ) |
            matedialog --progress \
              --title="Update System Logs" \
              --text="Scanning mail logs..." \
              --percentage=0

            if [ "$?" = -1 ] ; then
                    matedialog --error \
                      --text="Update canceled."
            fi

### Esimerkki edistymisikkunasta

MateDialog progress dialog example

## Tekstinsyöttöikkuna

Use the `--entry` option to create a text entry dialog. MateDialog returns the contents of the text entry to standard output.

Tekstinsyöttöikkuna tarjoaa seuraavat valitsimet:

`--text`=`teksti`

- Määrittää tekstin, joka näkyy tekstinsyöttöikkunassa.

`--entry-text`=`teksti`

- Määrittää tekstin, joka näytetään syöttökentässä teksinsyöttöikkunassa.

`--hide-text`

- Piilottaa tekstin syöttökentässä tekstinsyöttöikkunassa.

The following example script shows how to create a text entry dialog:

            #!/bin/sh

            if matedialog --entry \
            --title="Add an Entry" \
            --text="Enter your _password:" \
            --entry-text "password" \
            --hide-text
              then echo $?
              else echo "No password entered"
            fi

### Esimerkki tekstinsyöttöikkunasta

MateDialog text entry dialog example

## Tekstitietoikkuna

Käytä valitsinta `--text-info` luomaan tekstitietoikkuna.

Tekstitietoikkuna tarjoaa seuraavat valitsimet:

`--filename`=`tiedostonimi`

- Määrittää tiedoston, joka ladataan tekstitietoikkunaan.

`--editable`

- Sallii näytettävän tekstin muokkaamisen. Muokattu teksti palautetaan vakiotulosteeseen kun ikkuna suljetaan.

The following example script shows how to create a text information dialog:

            #!/bin/sh

            FILE=`matedialog --file-selection \
              --title="Select a File"`

            case $? in
                     0)
                            matedialog --text-info \
                              --title=$FILE \
                              --filename=$FILE \
                              --editable 2>/tmp/tmp.txt;;
                     1)
                            echo "No file selected.";;
                    -1)
                            echo "No file selected.";;
            esac

### Esimerkki tekstilaatikkoikkunasta

MateDialog text information dialog example