SceneBuilderin käyttö

Tässä dokumentissa käydään läpi miten teet SceneBuilderilla Java-sovellukseesi graafisen käyttöliittymän. Opit, mm.:

• Luomaan Eclipsellä JavaFX-projektin.
• Piirtämään yksinkertaisen käyttöliittymän SceneBuilderillä.
• Asentamaan omia komponentteja, jotka ovat .jar-tiedostossa.
• Ajamaan ohjelman Eclipsessä.
• Lisäämään yksinkertaisia tapahtuman käsittelijöitä, joista tulee “ei toimi”.
• Käsittelemään ohjelman sulkemisraksin.

Tähän osioon liittyviä lukuja kurssimonisteessa:

• 2.9 Graafiset käyttöliittymät

Tämä dokumentti sisältää ohjeita sekä tekstimuodossa että suunnilleen samansisältöisinä videoina. Ohjevideoilla käytetään seuraavia pikanäppäimiä:

1. Mikä on SceneBuilder?

SceneBuilder on graafinen työkalu, jonka avulla on helppo luoda ulkoasu ja graafinen käyttöliittymä (GUI) ohjelmaasi. SceneBuilder näyttää käytössä suunnilleen tältä:

Periaatteessa SceneBuilderilla voidaan rakennella graafisia käyttöliittymiä täysin ilman Eclipsen (tai vastaavan IDE:n) apua, mutta kun nyt kurssilla on tavoitteena tehdä sekä ohjelma, että sille käyttöliittymä on vain järkevää koordinoida käyttöliittymän ja ohjelman kehitystä yhdestä paikasta, tällä kurssilla siis Eclipsestä.

Periaatteessa JavaFX-ohjelman ulkoasu voitaisiin tehdä myös täysin ohjelmallisesti ilman SceneBuilderin kaltaista graafista työkalua, mutta ymmärrettävästi ulkoasun suunnittelu visuaalisesti on usein aluksi helpompaa.

Usein käytännössä graafista käyttöliittymää kehitetäänkin yhdistelemällä visuaalista ja ohjelmoinnillista työskentelyä. Esimerkiksi perussuunnittelu tehdään visuaalisella työkalulla ja sitten selkeästi toistuvia komponentteja lisätään ajonaikaisesti ohjelmakoodilla.

SceneBuilderilla luotujen ulkoasujen kuvauskielenä on FXML -formaatti, joka pohjautuu XML:ään. Tarkentimella .fxml olevia tiedostoja voidaan avata ja kirjoittaa myös millä tahansa tekstieditorilla, kuten NotePad++:lla tai Eclipsessä, ja niiden rakenne on aika ymmärrettävä. Eli pohjimmiltaan SceneBuilder on vain yksi vaihtoehto tietyn muotoisen xml-tiedoston muokkaamiseen.

Oraclen omat SceneBuilder-ohjeet löydät täältä, mutta pääset helpommin alkun tätä dokumenttia lukemalla ja upotettuja videoita katsomalla.

Aletaanpas tutustumaan tarkemmin itse käyttöön, mutta ennen kuin jatkat, niin varmista, että seuraavat on tehtynä:

• Java 13 asennus (luku 1)
• Eclipsen asennus (ainakin luvut 1-2)
• JavaFX-komponenttien ja SceneBuilderin asennus (luku 1 ja 2)
• Ali.jar, FXGui.jar (luku 5.2) Ilman tätä voi toki aloittaa, mutta silloin kohtaa Lisää oma ohj2-kirjasto ei voi tehdä. Ohjelman voi piirrellä, mutta ei ajaa jos kirjastot puuttuvat.

2. Projektin luominen Eclipsessä ja SceneBuilderin avaaminen

Seuraavan esimerkin tavoitteena on tuottaa valmiilta näyttävä, ajettava ohjelma mahdollisimman vähällä koodinkirjoittamisella. Tällaisen näköiskäyttöliittymän avulla olisi sitten helpompi keskustella esimerkiksi asiakkaiden kanssa.

Alta löydät ohjeet tekstimuodossa sekä videona.

Huom! videolla tehdään “väärän” niminen kontrolleri, se pitäisi olla KerhoGUIController. Käytännössä nimillä ei ole mitään merkitystä, mutta jos niitä vaihtaa luomisen jälkeen, niin niitä esiintyy useassa paikassa ja kaikki pitäisi osata vaihtaa. Tuo GUI on vaan kurssin nimeämistavan mukainen.

Aloitetaan luomalla Eclipseen uusi projekti.

Suositeltavaa on noudattaa ohjelmointikurssin nimeämiskäytänteitä. Korvaa alla olevassa esimerkissä kerho oman projektisi työnimellä ja vesal joko omalla käyttäjätunnuksella tai ryhmänne valitsemalla “projektinimellä”. Muista laittaa kerho samalla tavalla kirjoitettuna kuin mallissa (välillä isolla ja välillä pienellä).

1. Avaa Eclipse

2. Avaa valikosta: File / New / Other... / JavaFX / JavaFX Project ja paina ‘Next’

3. Täytä lomake seuraavasti

   • Project name: kerho
   • Use default location: ota ruksi pois
   • Location: C:\MyTemp\vesal\ohj2\kerho
     (Mac esim: /Users/vesal/ohj2/kerho)
   • tarkista että JRE on varmasti se jdk-13-JavaFX vaikka tarvittaessa ruksimalla se Use a project specific JRE: ja sieltä oikea JRE.

4. Paina Next, ruksi pois Create Module-info.java file ja sitten Next kunnes olet sivulla, jossa kysytään Application type
   

5. Täytä lomakkeen tiedot:

   • Application type: Desktop
   • Pacakage name: fxKerho
   • Language: FXML
   • Root type: javafx.scene.layout.BorderPane
   • FileName: KerhoGUIView
   • ControllerName: KerhoGUIController

6. Finish

7. Lisää oma ohj2-kirjasto (jos et ole tehnyt vielä tätä kirjastoa FXGui.jar-ohjeen mukaan, voit ohittaa tämän kohdan ja piirtää käyttöliittymät, mutta et voi ajaa ohjelmaa):

   • projektin nimen päällä hiiren oikeaa
   • Properties/Java Build Path
   • siirry Libraries-välilehdelle
   • valitse Add Library
   • sieltä tuplaklikkaa User Library ja ruksi ohj2
   • Apply and close

   Mikroluokissa voi joutua tekemään ohj2-kirjaston, ellei ole valmiina.

8. Jos olet asettanut Eclipsen varoitukset kurssin suositusten mukaan niin KerhoGUIController.java -tiedosto varoittaa virheestä, koska siinä olevasta luokasta puuttuu sisältö. Tästä pääset eteenpäin ihan vain lisäämällä luokan lohkosulkujen sisään kommenttimerkin: // Samoin valittaa puuttuvista kommenteista alleviivaamalla KerhoGUIController. Mene alleviivatun sanan päälle ja valitse Add javadoc comment. Myös Main luokassa lisää kommentit Main-sanan päältä ja main sanan pääältä. Ja main kommentteihin lisää vielä args jälkeen selitys:

    	 /**
    	  * @param args ei käytössä
    	  */

9. Mene vasemmalla olevan PackageExplorer -paneelin Main.java -tiedoston nimen päälle ja paina hiiren oikealla: Refactor/Rename ja vaihda nimeksi KerhoMain.java.

10. Vaihda application.css tiedoston nimeksi kerho.css.
    

11. Avaa KerhoMain.java ja vaihda myös siellä application.css tilalle kerho.css . Nyt pitäisi vasemman reunan näyttää seuraavalta:

    

12. valitse KerhoMain.java aktiiviseksi ja paina F11 ajaaksesi ohjelman.

13. Pitäisi aueta ohjelma, jossa on tyhjä dialogi.

14. Sammuta dialogi ja ehkä kannattaa KerhoMain-tiedostosta vielä poistaa koko rajoitteet 400,400. Eli se 400,400 pois, muuten rivi jää ennalleen.

Nyt voit avata SceneBuilderin klikkaamalla hiiren oikealla KerhoGUIView.fxml tiedostoa ja sitten Open with SceneBuilder. Ruutu näyttää tyhjältä, mutta siellä on pohjana yksi BorderPane.

HUOM! Projektin teko tuntuu varsin työläältä, mutta onneksi viime kevään kurssilaisista Antti teki asiaan helpotuksen, jolla kaikki saadaan yhdellä kysymyksellä. Eli jatkoa varten lue aikanaan ohjeet tuolta: fxmlpackage.jar.

3. Valmiiden apukomponenttien asentaminen

Kun piirretään harjoitustyön suunnitelma SceneBuilderillä, olisi se hyvä saada mahdollisimman aidon näköiseksi. Valmiilla komponenteilla ei monimutkaisempiin komponentteihin saa näköisdataa, esim. vakiokomponenteilla listat ovat tyhjiä, mikä vaikeuttaa hahmottamista. Tällä kurssilla onkin tarjolla avuksi muokattuja komponentteja, joihin voit syöttää “aidon näköistä” dataa, kuten esim. havainnekuvien jäsenlistauksen.

Toimi seuraavasti (videossa on Import JAR/FXML File..., nykyisin siinä on JAR/FXML Manager)

3.1 Omien komponenttien asentaminen

Kurssia varten on tehty käyttöliittymäkomponentteja sisältävä aliohjelmakirjasto, joka on FXGui.jar-nimisessä tiedostossa. Alla on ohjeet sen asentamiseksi:

1. Jos olet mennyt asennuksia huolella läpi, tämä kohta onkin jo tehtynä. Jos et, niin: Lataa tiedosto fxgui.jar joko c:\MyTemp\\ohj2\jar tai c:\devel\jar hakemistoon. Varmista, että tiedostopääte on latauksenkin jälkeen .jar, eli tiedoston kokonimi on fxgui.jar (jotkin selaimet - lue IE yms - vaihtavat ilman lupaa ladatessa tiedostopäätteeksi .zip jolloin tiedostopääte pitää itse muuttaa: “Nimeä uudelleen” fxgui.zip -> fxgui.jar).
2. Klikkaa SceneBuilderissä vasemmassa yläkulmassa Library -sanan oikealla puolella olevaa rattaan kuvaa.
3. Valitse JAR/FXML Manager.
4. Aukeaa Library Manager.
5. Valitse 1. kerralla Add Library/FXML from file system`.
6. Etsi äsken lataamasi .jar -tiedosto.
7. Paina OK.
8. Ruksi mitä komponentteja haluat asentaa (suositus on kaikki).
9. Paina Import Components.
10. Voit sulkea Library Managerin (muista mistä sen saa jatkossa käyntiin).
11. Uudet komponentit löytyvät Custom -paneelista.

Huom! Uudet komponentit täytyy käydä vielä lisäämässä Eclipsenkin puolella (paitsi jos lisäsit aikaisemmin ohj2-kirjaston, johon ne sisältyvät valmiiksi):

1. Package Exploreissa klikkaa hiiren oikealla painikkeella projektin nimeä ja valitse Properties
2. Valitse avautuvan ikkunan listalta Java Build Path ja sen välilehti Libraries
3. Jos on vaihtoehdot Module ja Classpath, niin klikkaa Classpath-kohtaa
4. Paina Add External JARs...
5. Etsi paikka mihin olet fxgui.jar-tiedoston tallentanut. Voit käyttää myös sitä Library paikkaa, johon SceneBuilder sen tallensi.

Huom! Omat komponentit voivat aiheuttaa kaikenlaisia epäyhteensopivuusongelmia. Tyypillisin on se, ettei .fxml-tiedostoa pysty avaamaan SceneBuilderiin Eclipsestä käsin, ratkaisu on avata tiedosto SceneBuilderin kautta. Kts. tämän sivun lopusta lisää.

3.2 Komponenttien päivittäminen

Tämä on tässä vaiheessa enemmänkin “nice to know” -tietoa.

Tapa 1: Poista vanhat ja asenna uudet:

1. Klikkaa SceneBuilderissä vasemmassa yläkulmassa Library -sanan oikealla puolella olevaa rattaan kuvaa
2. Valitse Jar/FXML manager
3. Library manager aukeaa
4. Sulje kaikki mahdollisesti auki olevat SceneBuilderit
5. Deletoi kaikki listassa olevat tiedostot jotka haluat päivittää.
6. Asenna tuoreet komponentit ylempänä olevan ohjeen mukaan.

Tapa 2: Asenna uudet vanhojen päälle:

1. Sinun täytyy tietää Library-hakemiston sijainti. Sijainti voi olla esimerkiksi: C:\Users\Vesa\AppData\Roaming\Scene Builder\Library
2. Sulje kaikki SceneBuilderit
3. Tallenna tuore komponenttipaketti (.jar) vanhan päälle.
4. Avaa SceneBuilder, päivitetyt komponentit ovat nyt käytössä.

4. Suunnitelman piirtäminen

Seuraavassa ohjeet hieman yksinkertaistetun suunnitelman piirtämiseksi (vastaa harjoitustyön mallin vaiheen 1 kuvaa):

4.1 Perusjako alueisiin

Käyttöliittymän tekemisen yksi lähtökohta on se, että käyttöliittymä mukautuu ikkunan (stage) koon muutoksiin. Siksi tehdessä pitää hieman miettiä minkälaisten pohjakomponenttien (Container) päälle itse komponentteja (Component) laitetaan.

Tässä harjoituksessa ikkunan käyttöliittymän asettelun pohjaksi on valittu BorderPane-niminen container, koska se jakaa mukavasti ikkunan viiteen eri osaan. Kaikkia osia ei ole aina pakko käyttää (tämän harjoituksen 1. vaiheessa käytämme vain neljää) ja container-komponentteja voi sijoittaa sisäkkäinkin.

Ennen kuin aloitetaan rakentelu, niin kurkataan hieman millaista lopputulosta kohti mennään. Seuraavassa kuvassa on näkymä SceneBuilder documentin hierarkiasta kun kaikki komponentit ovat paikallaan:

• Huom! Olethan asentanut kurssin FXGui.jar -apukomponentit?
• Vinkki: SceneBuilderissa valitse vasemman yläkulman Libraryn oikeanpuoleisen rattaan alta View as List, jolloin kaikki komponentit näkyvät samassa listassa.

Aloitetaan täyttämällä ensin ikkunan reunaosat:

1. Luodaan ikkunan alareunaan tila painikkeille HBoxin avulla
   • Avaa vasemmasta reunapaneelista Library/Containers -lista ja etsi HBox (huomaa, että voit käyttää myös hakua)
   • Raahaa HBox-elementti hiirellä BorderPane-alueen alareunaan (Bottom). Helpointa on raahata elementti vasemmalla olevaan Hierarchy -hierarkianäkymässä olevaan insert BOTTOM-kohtaan, koska itse käyttöliittymän kuva elää hyvin paljon kehityksen aikana mikä aiheuttaa helposti virhesijoituksia.
   • Säädetään seuraavaksi elementin asetukset: Varmista, että juuri pudottamasi HBox on valittuna ja avaa oikeasta reunasta ´Layout:HBox´
   • Vaihda Pref Width ja Pref Height koot asetukseen USE_COMPUTED_SIZE.
   • Aseta Spacing-kohtaan 10
   • Aseta kaikkiin Margin kohtiin 10. Tämä onnistuu helpostin kun laittaa ensimmäiseen 10 ja sitten klikkaa väkästä (>) joka vie saman muihin kohtiin
2. Lisätään painikkeet (Button):
   • Etsi Library/Controls-listalta Button ja vedä ne luomasi HBoxin päälle.
   • Vaihda painikkeisiin sopivat tekstit (esim Uusi jäsen ja Tallenna).
     • tuplaklikkaamalla tekstiä TAI
     • oikealta Properties:Button/Text TAI
     • vasemmalta `Hierarchy/HBox´ alta
3. Lisätään Menu-palkki (MenuBar):
   • Etsi Library/Controls-listalta MenuBar ja raahaa se BorderPane-alueen Top-osaan.
   • Pääset muokkaamaan menun tekstejä ja poistamaan tarpeettomia alavalintoja avaamalla MenuBarin rakenteen vasemman reunan Hierarchy-valikosta.
4. Luodaan uusi BorderPane valintalistaa ja sen otsikkoa varten:
   • Etsi Library/Containers-listalta uusi BorderPane ja raahaa se olemassa olevan BorderPanen Left-osaan.
   • Avaa uusi BordePane Hierarchy-näkymässä niin, että näet sen osa-alueet.
5. Lisätään valintalista (ListChooser) ja sille otsikko (Label):
   • Etsi Library/Controls-listalta Label, ja raahaa se uuden BorderPane alueen Top-osaan.
   • Vaihda sopiva teksti siihen (mallissa Jäsenet).
   • Olettaen, että olet asentanut FXGui.jar -apukomponentit, etsi Library/Custom-listalta ListChooser ja raahaa se uuden BorderPanen keskiosaan (Center).
     
   • Avaa oikealta Properties:ListChooser
   • Vie hiiri kohdan Rivit päälle.
   • jos ei ole monirivinen alue, niin paina oikeaan reunaan ilmestyvästä rattaasta Switch to multi-lines mode.
   • Kirjoita riveiksi sen, mitä haluat näkyvän listassa. Katso ettei alkuun jää tyhjää riviä.
6. Muista tallentaa aina välillä.

Seuraavaksi täytetään keskiosaa, johon pitää saada komponentit niin, että niiden koko muuttuu kun alueen kokoa muutetaan:

1. Luodaan alkuperäisen BorderPanen keskiosaan vieritettävä ScrollPane (empty) -osio: -Library/Containers: ScrollPane (empty)
   • Laita ruksi oikean reunan Layout:ScrollPane -paneelissa kohtaan Fit to Width, jotta se täyttää kaiken alueen tilan
2. Lisätään Library/Containers: GridPane edellä luodun ScrollPanenpäälle
   • Avaa Layout:GridPane -paneeli ja tee muutokset:
     • Hgap -kohtaan arvo 10, jotta sarakkeiden väliin tulee sopivasti tyhjää.
     • Padding-kohtiin muihin 10 paitsi alaosaan.
   • Klikkaa 0-sarakkeen otsikkoa ja Layout: ColumnConstraints-paneelista:
     • Pref Width -kohtaan USE_COMPUTED_SIZE
     • Poista ruksi kohdasta Fill Width
     • Vaihda Halignment-kohtaan RIGHT.
   • Klikkaa 1-sarakkeen otsikkoa ja Layout: ColumnConstraints-paneelista:
     • Katso että Fill Width -kohdassa on ruksi
     • Vaihda HGROW -kohtaan Always.
     • Tarkista että leveydet ovat USE_COMPUTED_SIZE.
3. Lisätään Label -komponentteja 0-sarakkeen eri riveille ja vaihdetaan niihin sopivat otsikot.
   • Uusia rivejä saat raahaamalla komponentin tarkasti GridPane-komponentin alareunaan TAI klikkaamalla hiiren oikealla napilla rivinumeroa.
4. Lisätään TextField-komponentit 1-sarakkeen riveille
   • Raahaa Library/Controls: TextField
   • Layout: TextField: Vaihda HGROW-kohtaan Always. (Videossa tätä ei tarvinnut tehdä, kokeile ilman ja kerro toimiiko!)

Kokeillaan toimiiko komponenttien skaalaus: Paina Ctrl+P (Mac: Cmd+P) ja muuttele “ohjelman” kokoa ja katso että TextField pienenee ja kasvaa halutulla tavalla. Samoin katso että ScrollPane alueen vierityspalkki tulee kun kokoa muutetaan riittävän pieneksi.

Sitten vielä lisää loput TextField -komponentit ottamalla kopio alkuperäisestä ja pastea niitä riittävä määrä. Ne voivat mennä väärään ruutuun, mutta raahaa ne siltä paikalleen. Laita kuhunkin TextField -kenttään malliksi sopiva teksti jotta käyttöliittymä näyttää aidommalta.

Nyt ulkoasun pitäisi olla suunnitelman mukainen. Seuraavaa vaihetta varten vielä pieni viimeistely.

4.2 Viimeistely

Luonnollisesti haluamme lisätä käyttöliittymään uusia käyttäjiä helpottavat Tooltipit sekä tottuneita käyttäjiä helpottavia pikavalintoja.

Tooltippien lisääminen:

0. Madalletaan ensin vähän rivejä: Valitse kaikki rivit pitämällä Ctrl pohjassa ja klikkaile rivinumeroita ja sitten valitse Pref Height kohtaan USE_COMPUTED_SIZE. Huom. Tätä ei kannata tehdä ennen kuin kaikki labelit ovat paikallaan, koska muuten rivit kutistuvat niin pieniksi että niihin on vaikea pudottaa.
1. Etsi Tooltip (Miscellaneous) ja raahaa Button-komponentin päälle.
2. Vaihda siihen sopiva teksti.
3. Tee sama muillekin painikkeille.

Pikavalintojen lisääminen:

Esimerkiksi haluamme että Uusi jäsen-painike aktivoituu painamalla näppäimistöltä Alt-U. Toimitaan seuraavasti:

1. Valitse Uusi jäsen -painike
2. Etsi oikealla olevasta Properties-paneelista kohta Mnemonic Parsing ja laita siihen ruksi.
3. Properties-paneelin yläosaan ja lisää Text-kentässä painikkeen nimen eteen alaviiva (_Uusi jäsen)
4. Nyt kirjain, joka on alaviivan jälkeen, toimii pikavalintana kun Alt on painettuna.
5. Lisää samalla tavalla pikavalintoja kaikkiin painikkeisiin ja menuihin.

Lisätään Tallentaminen valinnalla Ctrl-S:

1. Valitse Tallenna -menu item
2. Etsi Properties-paneelista Accelerator
3. Tästä aukeaa valikko, jossa on kolme kohtaa:

• ota ensimäiseen CONTROL_DOWN,
• toiseen none
• ja viimeiseen S. Hieman hassusti noilla valikoilla ei ole sulkemisnappia, vaan valinta tulee voimaan kun poistut sen alueelta.

4. Lisää samalla tavalla pikavalinnat muihin menutoimintoihin

• Lopeta -kohtaan Ctrl-Q
• uuden jäsenen lisäämiseen Ctrl-N.

VINKKI: Tämä on hyvä paikka ottaa käyttöliittymästä ruutukaappauksia Harjoitustyön 2. vaihetta varten.

4.3 Malliohjelman tiedostot

Voit avata alle mallia tehdessä syntyneet tiedostot, joita voit verrata omiisi. Tai voit niitä myös kokeilla muutella ja ajaakin, kunhan painelet noiden Tallenna, Käännä ja Aja-painikkeita järjestyksessä.

5. Yksinkertaisen koodin lisääminen

Seuraavaksi palaamme takaisin Eclipsen puolelle. Ensin pari vinkkiä, jotka voivat ennakoivasti auttaa näennäisissä vikatilanteissa:

FXML-tiedostojen päivittämisestä: Kun kehitystyössä pompimme Eclipsen ja SceneBuilderin välillä, on meidän syytä huomioida, että välillä Eclipse huomaa automaattisesti SceneBuilderia käytettässä .fxml-tiedostoon syntyneet muutokset ja välillä ei. Saat päivitettyä muutokset klikkaamalla projektin nimen päällä hiiren oikeaa nappia ja valitsemalla Refresh (pikavalintana F5). Elleivät muutokset vieläkään päivity, niin olethan varmasti muistanut tallentaa tekemäsi muutokset SceneBuilderissa?

FXML-tiedostojen tarkastelusta. Kohti edistyeempää käyttöä:* Muistathan, että voit avata .fxml-tiedoston Eclipsellä XML-muodossa ottamalla hiiren oikealla tiedoston nimen päällä ja Open With/FXML editor. Tällöin voit itse varmistua, mitä muutoksia tiedostoon syntyy, kun muokkaat sitä SceneBuilderissa. Huomaa, että voi tehdä muutoksia myös suoraan tekstieditorissa – se voi tuntua alkuun hieman vieraalta, mutta on pohjimmiltaan aika yksinkertaista.

Varmistetaan, että ohjelma käynnistyy: Avaa Eclipsessä KerhoMain.java ja kokeile ajaa se (F11).

Jos saat virheen puuttuvasta ListChooser-komponentista, niin et ole vielä kertonut Eclipselle, että käytössämme on omia komponentteja. Ohjeet löytyvät yllä olevalta videolta, mutta lyhyesti summattuna:

1. Package Exploreissa klikkaa hiiren oikealla painikkeella projektin nimeä ja valitse Properties
2. Valitse avautuvan ikkunan listalta Java Build Path ja sen välilehti Libraries
3. Paina Add External JARs...
4. Etsi paikka mihin olet fxgui.jar-tiedoston tallentanut. Voit käyttää myös sitä Library paikkaa SceneBuilder sen tallensi.
5. Nyt pitäisi koodi jälleen olla ajettavissa. Kokeile. (Ja muistathan, että jos .fxml-tiedostot eivät aukene SceneBuilderiin Eclipsestä käsin, joudut avaamaan ne itse SceneBuilderista: File/Open)

Kommentit kuntoon. Hyvän tavan ja kurssin vaatimusten mukaisesti laitetaan kommentit kuntoon. Aloita kommentoimalla KerhoMain.java -tiedostossa itse luokka ja main-metodi: Kirjoita yläpuolelle

/**

ja paina return. Tällöin Eclipse täydentää kommenttien pakolliset osat ja voit itse täydentää ne loppuun.

Siirrytään varsinaiseen toiminnallisuuksien lisäämiseen:

Kutsuttavien metodien lisäys. Jotta graafiseen käyttöliittymään luomamme painikkeet tekisivät jotain Java-ohjelmassamme, meidän täytyy Eclipsessä lisätä KerhoGUIController.java-tiedostoon metodeja, joita painikkeet kutsuvat. Lisätään ensin koodi:

Avaa Eclipsessä KerhoGUIController.java-tiedosto ja lisää KerhoGUIController-luokan sisään metodeja tyyliin:

package fxKerho;
import javafx.application.Platform;
import javafx.fxml.FXML;
import javafx.fxml.Initializable;
import java.net.URL;
import java.util.ResourceBundle;

import fi.jyu.mit.fxgui.*;

/**
 * Luokka kerhon käyttöliittymän tapahtumien hoitamiseksi.
 * @author vesal
 * @version 3.1.2018
 */
public class KerhoGUIController implements Initializable {

    @Override
    public void initialize(URL url, ResourceBundle bundle) {
        //
    }

    /**
     * Käsitellään uuden jäsenen lisääminen
     */
    @FXML private void handleUusiJasen() {
        Dialogs.showMessageDialog("Ei osata vielä lisätä");
    }
    
    
    /**
     * Käsitellään tallennuskäsky
     */
    @FXML private void handleTallenna() {
        tallenna();
    }
    
    
    /**
     * Käsitellään lopetuskäsky
     */
    @FXML private void handleLopeta() {
        tallenna();
        Platform.exit();
    }

    
    /**
     * Tietojen tallennus
     */
    private void tallenna() {
        Dialogs.showMessageDialog("Tallennetetaan! Mutta ei toimi vielä");
    }

}

Metodikutsujen lisäys SceneBuilderissa Seuraavaksi lisäämme SceneBuilderissa painikkeille ja valikoille ohjeet, että mitä koodissa olevaa metodia kukin niistä kutsuu:

Avaa taas SceneBuilder:

1. Valitse vaikka Uusi jäsen -painike.
2. Etsi oikeasta reunan Code-paneelista kohta On Action
3. Kun painat sen alasvetovalikkoa, niin näet kaikki @FXML-merkityt metodit: Valitse tässä tapauksessa handleUusiJasen – tämä on siis metodi, jonka lisäsimme juuri edellä koodiin.
   • Huom! Jos alasvetovalikkoa ei jostain syystä ole, niin kirjoita On Action-kenttään risuaita ja metodin nimi, esim.: #handleUusiJasen
4. Liitä vastaavasti tapahtumat kaikkiin muihinkin painikkeisiin ja menukohtiin.
5. Voit tarkistaa Eclipsessä KerhoGUIView.fxml-tiedostoa silmäilemällä, että homma meni oikein. Siellä pitäisi olla rivi tyyliin (rivillä voi olla myös muita attribuutteja, jos niitä on määritelty):

<Button onAction="#handleUusiJasen" text="Uusi jäsen">

Palaa Eclipseen ja kokeile ajaa ohjelma. Nyt ohjelman pitäisi reagoida menuihin ja painikkeisiin.

5.1 Tallentaminen kun ohjelma loppuu

Menuvalintaan lisätyn Lopeta-kohdan kautta ohjelma kyllä kiertää tallenna-metodin kautta kun ohjelma lopetetaan sitä kautta, mutta mikäli ohjelma suljetaan esim. painamalla Windowsissa ikkunan oikean ylänurkan ruksia, onnistutaan kiertämään tallennusvaihtoehdot. Tämän korjaaminen on tehty lievästi haastavaksi JavaFX:ssä, mutta onnistuu start-metodia muokkaamalla:

Ongelma: Ikkunan sulkeminen ohittaa tallennuksen.

Ratkaisu: Muokataan KerhoMain.java-tiedoston sisältämää start-nimistä käynnistysmetodia. Tarvittava koodi on luotu sinulle alle jo valmiiksi - meidän ei tarvitse nyt syventyä siihen sen tarkemmin, mutta muutoksen tarkoituksena on, että kun KerhoGUIView.fxml-tiedosto luetaan ja siitä muodostetaan käyttöliittymä ja luodaan controller-luokka, niin samalla otetaan tuo controller-luokan viite talteen.

Muutos start-metodiin: Kopioi siis alla olevan koodin oman ´start´-metodisi päälle, mutta muista korjata kaikki viittaukset projektin tiedostoihin, nimiin ja muuttujiin niin että ne vastaavat omaasi - käy koodi läpi ja sinun pitäisi tunnistaa jotakuinkin 6 korjattavaa kohtaa. Nyt on hyvä tilaisuus harjoitella koodin kommentointia, jotta löydät tekemäsi muutokset jos myöhemmin huomaat tehneesi virheen.

Myös pitää lisätä import riveihin (vastaava BorderPane-rivi voi muuttua tarpeettomaksi):

import javafx.scene.layout.Pane;

koska tuolla viitataan luokkaan Pane. Kohti edistyneempää käyttöä: Voit toki vertailla omaa ja allaolevaa koodia ja tehdä tarvittavat muutokset rivi kerrallaan – siinä samalla jää ehkä paremmin muistijälkiä metodin rakenteesta :)

public void start(Stage primaryStage) {
    try {
        FXMLLoader ldr = new FXMLLoader(getClass().getResource("KerhoGUIView.fxml")); // korjaa tiedostonimi
        final Pane root = (Pane)ldr.load();
        final KerhoGUIController kerhoCtrl = (KerhoGUIController)ldr.getController(); // korjaa nimet
        
        final Scene scene = new Scene(root);
        scene.getStylesheets().add(getClass().getResource("kerho.css").toExternalForm()); // korjaa tiedostonimi
        primaryStage.setScene(scene);
        primaryStage.setTitle("Kerho"); // korjaa title
        
        // Platform.setImplicitExit(false); // jos tämän laittaa, pitää itse sulkea
        
        primaryStage.setOnCloseRequest((event) -> {
            // Kutsutaan voikoSulkea-metodia
            if ( !kerhoCtrl.voikoSulkea() ) event.consume(); // korjaa nimi
        });
        
        primaryStage.show();
    } catch(Exception e) {
        e.printStackTrace();
    }
}

Dokumentissa JavaFX/kaytto on kuvattu tarkemmin mitä mikäkin rivi edellä tarkoittaa. Tässä vaiheessa voidaan toki vielä mennä ajatuksella “nuo siinä pitää olla”.

Mitä tapahtui? Metodiin start lisättiin kuuntelija sille, että kun käyttäjä haluaa sulkea ohjelman, niin ohjelma kysyy controller-luokan metodilta voikoSulkea, että saako ohjelman sulkea vaiko ei. Mikäli metodi vastaa “ei saa”, niin poistetaan sulkemistapahtuma jonosta ja estetään sulkeminen. Nyt controller-luokka voi itse päättää salliiko se ohjelman sulkeutumisen ja samalla tallentaa tiedot jos haluaa. Mutta meiltähän vielä puuttuu se voikoSulkea-metodi, jota nyt kutsumme, joten…

Lisätään voikoSulkea-metodi. Seuraavaksi meidän täytyy luoda edellä luotuun kutsuun vastaava metodi. Sen sijoitamme KerhoGUIController.java-tiedostossa esiteltyyn KerhoGUIController-luokkaan, siis sinne minne aikaisemmin loimme tapahtumakäsittelijöitä. Lopullisessa ohjelmassa metodi tekisi erilaisia tarkastuksia, mutta tässä vaiheessa pärjäämme yksinkertaisella koodilla, jonka voit kopioida alta:

    /**
     * Tarkistetaan onko tallennus tehty
     * @return true jos saa sulkaa sovelluksen, false jos ei
     */
    public boolean voikoSulkea() {
        tallenna();
        return true;
    }

Myöhemmin tehtäviä muutoksia: Tulevaisuudessa tässä metodissa tietysti tarkistetaan onko tallentamiselle tarvetta ja jos on, niin kysytään käyttäjältä mitä hän haluaa tehdä.

Voit katsoa miltä tiedostot näyttävät tämän vaihen jälkeen.

6. Dialogi-ikkunoiden luominen (suunnitelmaa varten)

Alta löydät vinkkejä dialogien luomiseen harjoitustyön suunnitelmaa (ja myös itse harjoitustyötä varten). Kokeile esimerkiksi ajaa seuraava yksinkertaisen dialogin luova ohjelma:

Terminologiakertaus: “Dialogilla” tarkoitetaan ikkunoita, jotka haluavat käyttäjältä jonkin syötteen, olipa se sitten napin painallus tai tekstiä. Dialogi-ikkunat voidaan jakaa modaalisiin (mikään ei etene, ennen kuin käyttäjä on vastannut siihen) ja ei-modaalisiin (syöte ei ole pakollinen tai käyttäjän annetaan käyttää samalla muita toimintoja, myös ohjelman työkalupaneelit ovat ei-modaalisia dialogeja). Suppeimmillaan dialogi kostuu yhdestä painikkeesta (esim. kuitataan pop-up -huomautus virheestä), laajemmillaan täytetään kokonaista lomaketta.

Yksinkertaisten dialogien lisäämisestä: Hyvin yksinkertaisia dialogeja varten ei itse kannata koodia koodia kirjoittaa, koska niitä löytyy JavaFX:stä valmiina ja myös lisäämästämme FXGui-kirjastosta vielä helpommin. Suositeltavaa on tutustua TIM:issä olevaan JavaFX-dialogeja käsittelevään sivuun, josta löydät ohjeita ja mikä parasta: valmista koodia, jota voit muokata ja testata suoraan TIM:issä! Huomaa, että TIM tulostaa dialoginäkymiä kuvina, joita voit hyödyntää harjoitustyösuunnitelmasi liitteenä! Vaihda em. sivulla oleviin esimerkkikoodeihin oman työsi vaatimia tekstejä ja kaappaa sitten kuvia. Otsikkopalkkia ei tule TIMissä oleviin dialogeihin, mutta siitä ei tarvitse tässä vaiheessa huolestua.

Monimutkaisempien dialogien lisäämisestä: Mikäli suunnitelmassasi on useampia “ei yksinkertaisia” dialogeja, voit lisätä niitä projektiisi seuraavalla tavalla:

1. Eclipsessä paina hiiren oikealla painikkeella packagen nimen (esimerkissä fxKerho) päällä:
2. Valitse New/Other.../JavaFX/New FXML Document/Next
3. Anna hyvä nimi tyyliin TulostusView
4. Avaa tiedosto SceneBuilderissa ja luo halutun kaltainen ikkuna
5. Aja ikkuna Ctrl-P:llä (Mac Cmd-P) ja kaappaa kuva suunnitelman dokumenttia varten.

7. Täydellisempi suunnitelma

Varsinaista suunnitelmaa varten tarvitaan enemmän komponentteja.

Kerho-esimerkissä lisätään harrastuksia varten StringGrid ja sitten muutama muu omatekoinen ikkuna. Varsinainen pääikkuna jaetaan keskeltä kolmeen osaan, joiden rajaa voidaan siirtää. Tähän käytetään SplitPane -containeria.

Seuraavassa kuvassa on näkymä SceneBuilder dokumentin hierarkiasta täydellisemmässä suunnitelmassa kun kaikki komponentit ovat paikallaan:

Voit katsella edellä olevaa tiedostoa kokonaisena klikkaamalla oikeassa alakulmassa pienellä olevaa nimeä. Tai voit ladata sen SceneBuilderillä avattavaksi klikkaamalla oikealla ja valitsemalla linkin tallennuksen.

Voit katsoa miltä tiedostot näyttävät tämän vaihen jälkeen.

7.1 Alkuperäisen piirroksen muuttaminen laajemmaksi

Uutta suunnitelmaa varten tarvitsemme keskelle SplitPanelin jolla voidaan jakaa keskiosan aluetta käyttäjän tarpeiden mukaan eri kokoisiin osiin. Ohjeissa siirrellään aluksi valmiita kokonaisuuksia pois tietä, jotta saadaan BorderPanen keskiosa käyttöön. SceneBuilderissä voi myös luoda paneelin komponentin alle painamalla hiiren oikeaa ja Wrap in, jolla osin voisi kiertää tuota siirtämisen ongelmaa.

Keskiosan alueen jakaminen kolmeen osaan:

1. Lisää alkuperäisen BorderPanen oikeaan reunaan uusi BorderPane.
2. Lisää sen yläosaan Label jossa lukee Jäsenen tiedot.
3. Vaihda tästä BorderPanesta layoutista kaikki koot lasketuiksi.
4. Raahaa se ScrollPane, jossa on GripPane jäsenen tietojen BorderPanen keskelle.
5. Lisää alkuperäisen BorderPanen nyt vapaaseen keskiosaan SplitPane (empty).
6. Raahaa Jäsenet BorderPane SplitPanen päälle.
7. Vaihda Jäsenet BorderPanelle rajat joissa sen koko voi liikkua:
   • Layout/Min Width: 100
   • Layout/Perf Width: 138
   • Layout/Max Width: 160
8. Raahaa Jäsenen tiedot BorderPane SplitPanen päälle.
9. Lisää vielä SplitPanen päälle yksi BorderPane harrastuksia varten.
10. Vaihda Splitpanen koot lasketuiksi.
11. Lisää harrastusten BorderPaneen yläreunaan Label jossa lukee Jäsenen harrastukset.
12. Lisää harrastusten BorderPanen keskellä Custom-kohdasta StringGrid.
13. Kirjoita StringGrid komponentin Rivit ominaisuuteen muodossa (ensin kannattaa valita vieressä olevasta rattaasta Switch to multine mode, joskus tämä näkyy ja joskus ei, jos valinnat ovat näkymättömiä, on tämä alin niistä):

ala|aloitusvuosi|h/vko
kalastus|1955|20
laiskottelu|1950|20
työn pakoilu|1952|40

14. Raahaa SplitPanen rajoja sopivasti. Jakokohdat näet numeerisena ominaisuudesta Divider Positions
15. Kokeile Ctrl-P:llä miten skaalautuu kun kokoa muutetaan.

Lisätään seuraavaksi vielä jäsenlistan päälle hakuehdot:

1. Siirrä tilapäisesti Label Jäsenet oman BorderPanensa alareunaan.
2. Lisää tämän BorderPanen yläreunaan VBox
3. Vaihda VBoxin kaikki koot lasketuiksi.
4. Lisää VBoxin sisälle järjestyksessä:
   • Label jossa lukee Hakuehto
   • Custom-kohdasta ComboBoxChooser ja kirjoita sen Rivit ominaisuuteen samat tekstit jotka ovat Jäsenen tiedot kohdassa otsikoina, eli nimi, hetu jne.
   • TextField
5. Rahaa Jäsenet-label VBoxiin.
6. Labelit saat alueensa keskelle vaihtamalla:
   • Layout/Max Width: 300
   • Properties/Node/Alignment: Center
7. Vaihda ComboBoxChooserille: Layout/Max Width: 300
8. textFieldille vaihda kaikki koot lasketuiksi jolleivat jo ole.

Laitetaan alareunaan 4 painiketta kahdesa ryhmässä. Tätä varten lisätään BorderPane, jonka laidoille laitetaan HBoxit joissa painikkeet ovat:

1. Siirrä tilapäisesti painikkeiden nykyinen HBox uloimman BorderPanen oikeaan reunaan.
2. Lisää uloimpaan BorderPaneen alareunaan uusi BorderPane. Koot lasketuiksi.
3. Siirrä painikkeiden HBox alareunan BorderPanen vasempaan reunaan.
4. Lisää oikeaan reunaan uusi HBox. Koot lasketuiksi. Katso muut asetukset alkuperäisestä HBoxista.
5. Lisää oikean reunan HBoxiin painikkeet Lisää harrastus ja Poista harrastus.
6. Lisää vastaavat menukohdat Muokkaa menun alle.

Esimerkiksi tämä viimeinen muutos olisi voitu tehdä myös niin, että valitaan ensin HBox ja sitten hiiren oikella Wrap In ja sieltä valitaan BorderPane. Oletuksena olisi mennyt väärään osaan (alaosaan), mutta sieltä on helppoa raahata HBox vasempaan reunaan. Sitten olisi jatkettu kuten yllä.

8. Muiden itsepiirrettyjen dialogien näyttäminen

Erikseen piirrettyjen dialogien näyttäminen vaatii jo ohjelmakoodia. Sitä voit katsoa malliharjoitustyön vaiheesta 3:

• avaa linkki https://www.mit.jyu.fi/demowww/ohj2/ht17/vesal/vaihe3/
• katso linkistä fxKerho/KerhoGUIController.java mitä koodia on jaettu .fxml-tiedostolle ja tietysti vastaavasti liitetty siellä paikalleen.
• katso tapahtumankäsittelymetodista handleTietoja miten AboutView.fxml näytetään kun Tietoja-valintaa klikataan
• tapahtumankäsittelymetodissa handleTulosta kutsutaan itse tehdyn luokan (lisätty ihan uusi Class Ecplipsessä) TulostusController staattista metodia tulosta
• katso TulostusController.java tiedostosta miten tämä luokka on tehty ja mitä siitä on jaettu vastaavaan .fxml -tiedostoon.
• lisäesimerkki vaikkapa jäsenen tietojen kysymisestä on yksinkertaisen dialogiesimerkin vaiheessa 3.
• ole erityisen tarkkana kontrollerin nimen kanssa että paketin nimi ja luokan nimi ovat juuri oikein.

9. Komponenttien värien muuntelu

Komponenttien värien muuntelu kannattaa tehdä tyylitiedostojen avulla. Tyylitiedoston näet Eclipsessä .css-päätteisenä tiedostona - tämän harjoituksen esimerkissä se olisi kerho.css.

CSS-tyyliohjeet ovat ehkä osalle tuttuja WWW-suunnittelusta.

Löydät lisäohjeita tyylitiedostojen käyttöön JavaFX:n käyttöä käsittelevästä TIM-dokumentista.

10. Kuvien käyttäminen

Jotta käyttöliittymään lisätyt kuvat näkyisivät sekä SceneBuilderissa että ajettavassa JAR-tiedostossa, kannattaa kuvat sisältävä hakemisto siirtää sen paketin sisään, jossa käyttöliittymän FXML-tiedostot sijaitsevat (yleensä fxHarkannimi-niminen paketti).

Jos olet ennen tätä ehtinyt jo lisätä kuvia SceneBuilderissa poimien kuvat jostain muualta, niin näiden kuvien polut täytyy korjata muotoon

<Image url="@kuvat/jokukuva.png" />

jossa kuvat-hakemisto sijaitsee fxHarkannimi-paketissa. Kuvahakemisto voi sisältää alihakemistojakin.

11. Lisää ymmärrystä JavaFX:ään

• heti kun olet valmis ymmärtämään (voi olla ettei kurssin parilla ekalla viikolla, mutta kokeile aina välillä) tee harjoitus: JavaFX käyttö.
• tämä on myöhemmin kurssilla demotehtävä, niin kaikki mitä olet tästä tehnyt, on kotiinpäin ja auttaa ymmärtämään kurssin luentoja paremmin.

12. fxgui:n ja SceneBuilderin yhteiskäytön ongelmia

12.1 Omia komponenttikirjastoja sisältävien projektien avaaminen SceneBuilderilla

Ongelma: Monesti erityisesti mikroluokissa omia komponenttikirjastoja käyttävien .fxml-tiedostojen uudelleenavaamisessa Eclipsen kautta tulee ongelmia, ja SceneBuilder näin avattuna kaatuu.

• Ratkaisu: Ennen kuin aloitat työskentelyn Eclipsellä, avaa SceneBuilder ja lisää kaikki käyttämäsi omat komponenttikirjastot SceneBuilderiin mukaan. Tämän jälkeen tiedostojen avaaminen Eclipsen kautta (Open with SceneBuilder) pitäisi onnistua tällä kirjautumiskerralla. Huom: Tämän voi joutua mikroluokissa tekemään joka kerta uudestaan.

12.2 Kurssin omien komponenttien asentamisen tuomat ongelmat

Ongelma: Kurssin omien komponenttien käyttö vaikuttaisi monissa tapauksissa johtavan tilanteeseen, jossa .fxml-tiedostoa ei enää pysty aukaisemaan Eclipsestä käsin SceneBuilderiin.

• Ratkaisu 1: Käynnistä ensin SceneBuilder ja avaa haluttu tiedosto sen sisältä: File/Open
• Ratkaisu 2: Pidä koko ajan käynnissä yksi SceneBuilder, johon on ihan sama mitä siihen on avattuna. Silloin SceneBuilder on ladannut kirjaston ja kun toinen aukeaa, niin kirjasto on valmiina.

12.3 ListChooser ja margin

Jos ListChooserin laittaa GridPanelin sisään ja laittaa ListChooserille marginia, niin tallennuksen jälkeen SceneBuilder ei enää suostu avaamaan tiedostoa ennen kuin poistaa fxml-tiedostosta margin-tagin:

<GridPanel.margin>
...
</GridPanel.margin>

Ongelma saattaa ilmaantua myös muiden kuin GridPanelin kanssa. Ja ilmeneekin monella muulla tavalla ja tuo SceneBuilderin avaaminen ensin erikseen ja sitten File/Open ja etsii muokattavan .fxml-tiedoston.

12.4 SceneBuilderilla piirretyn käyttöliittymän kontrolleri

1. Valitse View/Show Sample Controller Skeleton.
2. Kopioi leikepöydälle Copy.
3. Siirrä valmis runko Eclipsen puolella uuteen java-tiedostoon.