JEWL.IO Podręcznik Użytkownika

Ten dokument jest częścią biblioteki JEWL, prawa © John English 2000. To oprogramowanie zostało wydane zgodnie z założeniami GNU Powszechnej Licencji Publicznej, i może być kopiowana, rozpowszechniana i używana zgodnie z jej zasadami. Sugestie, komentarze, błędy i modyfikacje powinny być przesyłane do autora <je@brighton.ac.uk>.

Zawartość

1. Wstęp
2. Nie-graficzne (Non-GUI) możliwości wejścia i wyjścia
3. Wejście dla Stringów
4. Wejście standardowych typów
5. Podstawowe możliwości wejścia
6. Wiadomości
7. Dialogi plikowe

1. Wstęp

JEWL (John English's Window Library) jest zbiorem pakietów języka Ada przeznaczonych dla początkujących, które pozwalają na tworzenie względnie skomplikowanych pod względem graficznym aplikacji, przy minimalnym wysiłku. Pakiety zostały zaprojektowane, by być niezależnymi od systemu, jednak aktualnie jedyną implementacją jest ta dla systemu Microsoft Windows. Przykłady w tym dokumencie bazują na tej właśnie implementacji.

JEWL.IO jest pakietem, który może w mniejszym lub większym stopniu zastąpić standardowy pakiet Ada.Text_IO i jego pochodne Ada.Integer_Text_IO oraz Ada.Float_Text_IO, co oznacza, że tradycyjnie tekstowe programy mogą być przeniesione do środowiska graficznego, bez większego wysiłku. JEWL.IO używa graficznych okienek dialogowych (zwanych w skrócie dialogami) by wprowadzać dane, każda dana jest przesyłaną także jako echo do standardowego wyjścia. To oznacza, że część programu, w której wprowadzamy dane, może zostać zrobiona z dialogów graficznych, podczas gdy wyjście wciąż będzie wypisywane do standardowego wyjścia. Fakt ten oznacza, że log wyjścia będzie dokładnym odbiciem tego, jakby program był w całości oparty na trybie tekstowym.

JEWL.IO zawiera także kilka dodatkowych udogodnień: na przykład, ułatwienia dotyczące generowania komunikatów o błędzie lub innych powiadomieniach użytkownika, jako wiadomości (które także są przesyłane do standardowego wyjścia); funkcje konwertujące dane do typów łańcuchowych string i do łączenia typów łańcuchowych string by uprościć wypisywanie na wyjściu; także zabezpieczenia jak procedury Put_Line dla typów innych niż string.

JEWL.IO dostarcza podobne operacje jak w Ada.Text_IO dodając jednocześnie nowe udogodnienia:

• Wejście i wyjście standardowych typów: String, Character, Integer, Float i Boolean
• Wejście i wyjście dla nowych typów i podtypów: typów wyliczeniowych, całkowitych i rzeczywistych
• Konwersje powyższych do stringów
• Standardowe zawiadomienia użytkownika: komunikaty o błędach, informacyjne i zapytania
• Operacje na plikach: otwieranie i tworzenie plików używając podstawowych dialogów, by wyznaczyć plik do otwarcia bądź utworzenia.

We wszystkich dialogach za wyjątkiem zawiadomień użytkownika występuje przycisk Anuluj, który pozwala anulować wprowadzanie do wejścia. Naciśnięcie tego przycisku (lub przycisku zamykającego na pasku tytułowym) w każdym przypadku zamknie okno dialogowe i wzniesie wyjątek o anulowaniu wejścia Input_Cancelled.

Następujące sekcje opisują wszystkie te aspekty dużo dokładniej. W każdym przypadku, nazwy użyte by opisać parametry są właściwymi nazwami użytymi w deklaracjach, więc procedury opisane jako Get(Prompt,Default) mogą być także wywołane w ten sposób:

    Get ("My prompt", "My default");

lub tak:

    Get (Prompt => "My prompt", Default => "My default");

lub tak:

    Get (Default => "My default", Prompt => "My prompt");

Także, nazwa każdej operacji w jej opisie jest połączona z wersją HTML w pakiecie specyfikacyjnym, więc po jej kliknięciu można zobaczyć jej formalny zapis.

2. Nie-graficzne (Non-GUI) możliwości wejścia i wyjścia

Wyjście jest bardzo podobne do tego, które dostarcza pakiet Ada.Text_IO. Są wspólne dla wszystkich typów danych obsługiwanych przez JEWL.IO (String, Integer, Float oraz Boolean; dowolny typ wyliczeniowy, całkowity lub rzeczywisty) jak również standardowy typ znakowy Character. Dostępne są następujące operacje wyjścia:

Put (Item)

Wypisuje zawartość Item do standardowego wyjścia.

 

Put (File, Item)

Wypisuje zawartość Item do pliku określonego przez File.

 

Put_Line (Item)

Wypisuje Item i nową linię do standardowego wyjścia.

 

Put_Line (File, Item)

Wypisuje Item i nową linię do pliku określonego przez File.

 

New_Line (Spacing)

Rozpoczyna nową linię tyle razy, ile podano w Spacing. Spacing jest parametrem opcjonalnym i jeśli zostanie pominięty, domyślna wartość przyjmowana jest jako 1.

 

New_Line (File, Spacing)

Rozpoczyna nową linię w pliku określonym przez File tyle razy, ile podano w Spacing. Spacing jest parametrem opcjonalnym i jeśli zostanie pominięty, domyślna wartość przyjmowana jest jako 1.

Dostępne są również standardowe operacje konwersji:

S := To_String(Item)

Konwertuje wartość (nie-string) Item do String.

T := S & X

Łączy String S i wartość X w pojedynczy String.

T := X & S

Łączy wartość X i String S w pojedynczy String.

Długość rezultatu funkcji To_String(Item) będzie zależeć od wartości parametru Item; analogicznie, długość S & X będzie zależała od wartości S i X. Takie 'niesprecyzowane' (unconstrained) łańcuchy mogą zostać przesłane do podprogramu, który oczekuje na taki właśnie typ, jako parametr (e.g. Put) ale mogą zostać przypisane tylko do zmiennej typu String (lub części zmiennej string) jeśli jest dokładnie odpowiedniego rozmiaru. Na przykład, następująca rzecz wygeneruje wyjątek Constraint_Error, jeśli rezultat To_String(Item) nie ma dokładnej długości 20 znaków:

    S : String(1..20) := To_String(Item);

Czasem łatwiej zadeklarować zmienną String o odpowiednim rozmiarze i zainicjalizować ją używając następującej deklaracji:

    declare
      S : String := To_String(Item);
    begin
      -- tutaj użycie wartości S
    end;

Granice S nie muszą być określone; rezultat To_String(Item) zostanie użyty by je określić.

Dodatkowe funkcje dotyczące użycia plików:

Skip_Line (File, Spacing)

Pomija tyle linii wejścia ile podano w Spacing. Spacing jest parametrem opcjonalnym i jeśli zostanie pominięty, domyślna wartość przyjmowana jest jako 1.

 

End_Of_Line (File)

Funkcja, która zwraca wartość prawdy True jeśli wejście określone w pliku File jest na końcu linii w tym pliku.

 

End_Of_File (File)

Funkcja, która zwraca wartość prawdy True jeśli wejście określone w pliku File jest na końcu pliku.

3. Wejście dla Stringów

Stringi są obsługiwane odrobinę inaczej niż pozostałe typy, ponieważ String jest 'nieskrępowanym' (unconstrained) typem, którego długość może być różna. Możliwe operacje to:

Get (Prompt, Default)

Ta funkcja wyświetla okno dialogowe, które pozwala użytkownikowi wprowadzić łańcuch znaków o nieskończonej długości (aż do bardzo dużej, określonej przez system operacyjny długości). Dialog ma tytuł "Input required" (Wprowadź dane) i zawiera określoną podpowiedź, pole wprowadzania by wprowadzić wymagany string, oraz przyciski OK i Anuluj. Pole edycyjne jest inicjalizowane wartością podaną w Default. Naciśnięcie przycisku OK zamyka okno dialogowe, i zwraca string jako wartość funkcji. Podpowiedź i to co wprowadził użytkownik są kopiowane do standardowego wyjścia dla potrzeb pliku log.

Ponieważ długość string'a jest nieznana, jedynymi miejscami, gdzie ta funkcja może być użyta są miejsca gdzie nieskrępowany string jest akceptowalny. Są parametrami do innych procedur lub funkcji:

    Put(Get(Prompt,Default));

lub w deklaracji:

    S : String := Get(Prompt,Default);

Obydwa parametry Prompt i Default są opcjonalne, więc najprostsza forma stosowania Get jest taka:

    S : String := Get;

Domyślnie , podpowiedź Prompt brzmi "Wprowadź swój tekst:" i Default jest pustym stringiem ("", zero znaków długości).

Get (Item, Length, Prompt, Default)

To jest procedura, która czyta string do zmiennej o określonej długości. Parametry Prompt i Default są używane tak jak zostały opisane wyżej. Item jest zmienną typu String a Length jest liczbą naturalną (Natural) (lub całkowitą Integer) oznaczającą długość. Tekst wpisany do pola wprowadzania jest kopiowany do Item jeśli Item ma odpowiednią długość. Jeśli Item nie ma odpowiedniego rozmiaru by przyjąć cały wpisany tekst, zostanie skopiowana tylko ta część która się mieści. Length zostanie ustawione na aktualną długość znaków skopiowanych do Item.

 

Get (File, Item, Length)

Jak wyżej, za wyjątkiem tego, że wejście pochodzi z pliku podanego w File, i żaden dialog nie jest używany (więc nie ma podpowiedzi ani domyślnej wartości).

By umożliwić kompatybilność z nazwami operacji z Ada.Text_IO, ostatnie dwie są dostępne pod różnymi nazwami:

Get_Line (Item, Length, Prompt, Default)

To samo co Get (Item, Length, Prompt, Default).

 

Get_Line (File, Item, Length)

To samo co Get (File, Item, Length).

Istnieje także wersja Get, która odczyta pojedynczy znak z pliku:

Get (File, Item)

Ta procedura czyta pojedynczy znak z pliku do zmiennej Item typu znakowego Character.

4. Wejście standardowych typów

Standardowe typy obsługiwane przez JEWL.IO (poza typem String, którego obsługa jest wyżej) to Integer, Float oraz Boolean. Nie ma wejściowych udogodnień dla pojedynczych znaków, jako że String lub typ wyliczeniowy jest zwykle lepszym wyborem dla tego typu wejścia. Jeśli to konieczne, udogodnienia dla typów wyliczeniowych opisane poniżej mogą być używane z typem znakowym Character.

Dla Integer, Float oraz Boolean, następujące operacje wejścia są dostępne:

Get (Item, Default, Prompt)

Używa dialogów GUI by odczytać wartość odpowiedniego typu do Item, wyświetlając Prompt jako podpowiedź, o początkowej wartości Default jako początkowa wartość okienka dialogowego. Obydwa Prompt i Default mogą być pominięte. Jeśli Prompt jest pominięte, standardowa podpowiedź zostanie wyświetlona w oknie dialogowym (e.g. "Wprowadź liczbę całkowitą:" dla typu Integer); jeśli Default jest pominięte, żadna domyślna wartość nie zostanie wyświetlona, kiedy okno dialogowe zostanie wyświetlone.

 

Get (File, Item)

Czyta wartość do Item z pliku podanego w File.

Dialogi dla Integer i Float używają takiego samego okienka jak dla String, za wyjątkiem tego, że dane wejściowe są sprawdzane co do typu, kiedy przycisk OK zostaje naciśnięty. Jeśli są nieprawidłowe, wiadomość o błędzie zostanie wyświetlona (zobacz Error, niżej) i dialog zostanie wyświetlony ponownie, jeśli OK zostanie naciśnięte jako odpowiedź.

Dialogi typu Bool mają odmienny wygląd, zależnie od tego czy wartość jest określona. Jeśli nie ma domyślnej, okienko zawiera określoną podpowiedź i trzy przyciski podpisane "Tak", "Nie" oraz "Anuluj". Naciśnięcie "Tak" zwraca wartość prawdy True, "Nie" zwraca fałsz False, a "Anuluj" wznosi Input_Cancelled - wyjątek jak zwykle.

Jeśli wartość domyślna istnieje, pole zaznaczania jest wyświetlone (podpisane odpowiednią podpowiedzią) razem z przyciskami "OK" i "Anuluj". Pole zaznaczania jest zaznaczone jeśli domyślną wartością jest prawda True.

5. Podstawowe możliwości wejścia

JEWL.IO podstawowych podpakietów dla wejścia i wyjścia typów wyliczeniowych, całkowitych i zmiennoprzecinkowych. By ich używać, muszą być zainstancjonowane z odpowiednim typem:

    package My_Enumerated_IO is new JEWL.IO.Enumeration_IO (My_Enum);
    package My_Integral_IO   is new JEWL_IO.Integer_IO (My_Int);
    package My_Float_IO      is new JEWL_IO.Float_IO (My_Float);

Operacje dostępne w tych pakietach są standardowymi operacjami wyjścia i następującymi operacjami wejścia (takie same jak opisane powyżej dla standardowych typów, wyżej):

Get (Item, Default, Prompt)

Używa dialogu GUI, by odczytać wartość odpowiedniego typu do Item, wyświetlając Prompt jako podpowiedź, z początkową wartością Default jako wartość początkowa dialogu. Prompt i Default mogą być pominięte. Jeśli Prompt jest pominięte, standardowa podpowiedź będzie wyświetlona (np. "Wprowadź liczbę całkowitą:" dla typu całkowitego); jeśli Default jest pominięte, żadna wartość początkowa nie będzie wyświetlona kiedy pojawi się okno dialogowe.

 

Get (File, Item)

Odczytuje wartość do Item z określonego pliku określonego przez File.

Dialogi dla typów całkowitych i zmiennoprzecinkowych używają tego samego dialogu co dialog dla String, za wyjątkiem tego, że wprowadzana wartość jest sprawdzana, by upewnić się czy po naciśnięciu OK, wszystko będzie w porządku. Jeśli wartość jest błędna, wiadomość o błędzie, która precyzuje dostępne wartości zostanie wyświetlona jako okno wiadomości (patrz Error , niżej) i dialog zostanie wyświetlony ponownie jeśli przycisk "OK" został naciśnięty jako odpowiedź.

Zauważ, że powinieneś unikać używania klauzuli use dla podtypów całkowitych lub zmiennoprzecinkowych, jako że to powoduje dwuznaczność między istniejącymi operacjami dla Integer i Float i tymi dostarczonymi w nowym pakiecie. Na przykład, rozważ co się stanie, jeśli Integer_IO jest zainstancjonowany dla Natural(nych) (jako podtyp Integer):

    package Natural_IO is new JEWL.IO.Integer_IO(Natural);
    use Natural_IO;

Jeśli Get jest wywołane dla Integer lub Natural, kompilator nie będzie w stanie rozróżnić pomiędzy dwoma dostępnymi wersjami Get:

    Get(Item);  -- czy to Get(Item:Integer) lub Get(Item:Natural)?

By rozstrzygnąć dwuznaczność, musisz sprecyzować nazwę pakietu w obu przypadkach:

    JEWL.IO.Get(Item);      -- Get(Item:Integer)
    Natural_IO.Get(Item);   -- Get(Item:Natural)

Jeśli nie ma klauzuli use dla Natural_IO, wersja Get dla typu Natural będzie wciąż musiała być zakwalifikowana jako Natural_IO.Get jak w drugim przypadku powyżej, ale Get(Item) bez dodatkowych kwalifikacji będzie teraz interpretowane bez dwuznaczności jako odwołanie do wersji Get dla typu Integer (pierwszy przypadek wyżej).

Dialog dla typów wyliczeniowych posiada Kombo zamiast pola edycji, i jeśli domyślna wartość została zdefiniowana, będzie wartością wyświetlaną początkowo w Kombo. Naciśnięcie klawisza na prawo od Kombo wyświetli opuszczaną listę możliwych wartości typu wyliczeniowego. Tylko wartości wyświetlone na tej liście mogą być wybrane; wartość Kombo nie może być edytowana wprost.

6. Wiadomości

Wiadomość jest dialogiem, który może zostać użyty do poinformowania użytkownika o błędzie lub innej informacji, lub zadać pytanie tak/nie. Są trzy operacje wyświetlające okna wiadomości:

Message (Text) Pokazuje okno informacji z przyciskiem "OK" i ikoną informacji. Text jest tekstem wiadomości, która pojawia się wewnątrz okna dialogowego. Wiadomość jest przesyłana jako echo do standardowego wyjścia.
Error (Text) Pokazuje wiadomość o błędzie z przyciskiem "OK" i ikoną błędu. Text jest tekstem wiadomości, która pojawia sięwewnątrz okna. Wiadomość jest także przesyłana jako echo do standardowego wyjścia.
Query (Text, Title) Pokazuje zapytanie z przyciskiem "Tak" i "Nie" oraz ikoną zapytania. Text jest tekstem wiadomości, która pojawia się wewnątrz okna dialogowego. To jest funkcja która zwraca wartość Bool, jako rezultat, która wynosi True, jeśli przycisk "Tak" został naciśnięty i False jeśli przycisk "Nie" został naciśnięty. Zapytanie i reakcja użytkownika jest przesyłana jako echo do standardowego wyjścia.

7. Dialogi plikowe

Dostarczone standardowe dialogi do otwierania i tworzenia plików. Wyświetlają drzewo katalogów i pozwalają wybrać lub ręcznie wpisać nazwę pliku do otwarcia lub utworzenia. W każdym wypadku parametr File identyfikuje plik będący otwartym bądź tworzonym i musi być zmienną typu File_Type. Procedury używające tych dialogów są następujące:

Open (File, Title)

Otwiera istniejący plik dla wejścia. Title jest tekstem, który zostanie wyświetlony w pasku tytułowym dialogu i jest opcjonalny; jeśli zostanie pominięty, tytuł "Otwórz plik" będzie użyty.

 

Create (File, Title)

Tworzy plik dla wyjścia. Jeśli plik o tej nazwie już istnieje, wyświetlona zostanie wiadomość pytająca, czy chcesz go nadpisać. Title jest tekstem, który zostanie wyświetlony w pasku tytułowym dialogu i jest opcjonalny; jeśli zostanie pominięty, tytuł "Zapisz jako" będzie użyty.

 

Append (File, Title)

Otwiera plik do dopisywania. Jeśli plik o tej nazwie nie istnieje, wiadomość zostanie wyświetlona, pytając czy chcesz go utworzyć. Title jest tekstem, który zostanie wyświetlony w pasku tytułowym dialogu i jest opcjonalny; jeśli zostanie pominięty, tytuł "Zapisz jako" będzie użyty.

Dialog będzie wyglądał tak:

Pliki powinny zostać zamknięte jeśli nie są dłużej w użyciu:

Close (File)

Zamyka określony plik, jeśli nie jest dłużej potrzebny.

---

Podręcznik Użytkownika JEWL.IO — © John English 2000,

przetłumaczył Piotr Śliwka 2004