= {iced} Application Framework
Rizzen Yazston
:iced-url: https://crates.io/crates/iced
:iced_aw-url: https://crates.io/crates/iced_aw
:i18n-url: https://crates.io/crates/i18n-rizzen-yazston
:icu-url: https://crates.io/crates/icu
:icu4x-url: https://icu4x.unicode.org/
:iced: pass:q[*iced*]

Welcome to the *{iced} Application Framework* project.

The goal is to provide a starting application framework for developing native multi-window {iced} applications.

This project uses the {iced-url}[{iced}] library crates (including {iced_aw-url}[*iced_aw*] community crate for additional widgets) for the GUI of the application.

In addition, the framework supports internationalisation by using the crate {i18n-url}[*i18n-rizzen-yazston*] and various crates of the {icu4x-url}[*ICU4X*] project, the main crate being {icu-url}[*icu*].

== Features

The following features are available:

* `sync`: To use `sync::Arc` instead of `rc::Rc`, their respective variants.

* `iced_aw`: This is only used when there is a cargo cache issue as a result of using the `iced` master branch with the `iced_aw` main branch. It is simply a copy of the `iced_aw` components used by this project.

== What is included

The application framework has the following capabilities:

* On first use the Preferences window will be displayed prompting the user to select the user interface language (currently using language tags while waiting for *display name* feature to be completed in ICU4X),

* The following windows:

** `ConfirmExit`: for demonstration purposes application is set to displayed when exiting (faking unsaved data),

** `Preferences`: contains the user interface language setting, and optional log level setting,

** `FatalError`: for displaying fatal error messages to users (helpful when not launched from console),

** `Information`: a simple generic window to display a message to user,

** `Default`: simply a main window containing a menu bar,

** `Main`: simply a main window containing a menu bar,

** `About`: simply demonstration of an about window.

* Parent windows are generally disabled while popup window is displayed,

* Traps the window decoration close button, to handle certain state cases,

* Windows are resizable and movable, and their final position and size is saved on application termination and restored when application is relaunched.

* Supports handling of error `Result`s internally of the `update()` method using FatalError window to display uncaught errors.

* Localisation of text and errors that supports internationalisation. Two demonstration languages included for almost all text. Deliberately the text displayed in Main window does not support localisation for demonstration purposes.

* A trivial example for localisation on selected platforms. For MacOS target the menu bar and Confirm Exit windows uses "Quit <app_name>" instead of "Exit".

== Usage

NOTE:: There are no build scripts included, and data files need to be copied to target destination.

As this project is a starting point for developing multi-windowed {iced} applications, it can be compiled into a functional example, and be launched by using the application name `example`.

Before launching the `example` copy the `l10n` directory to where the directory where the binary resides to avoid a panic indicating missing localisation database.

Edit the `src/application/constants.rs`, to configure various application's `const`s to reflect the new project.

== Notes

* Menu items are always centred, current implementation of `menu` in `iced_aw` does not have methods or means to change alignment to start or end.

* This still work in progress, thus the windows may look a bit wonky. Currently focused on functionality than appearances.

* Components (such as logging, command processing, session persistence) that are not used can be simply deleted for the application, thus simplifying the source code. The localisation can be removed, by hard coding actual strings in the various localisation files found in `src/localisation/` directory, and altering the file `src/core/localisation.rs` to remove the dependency on `i18n-rizzen-yazston` crate.

== Adding a new windows

* In `src/window` directory pick a window that closely fits your new window layout structure, copy rust file with a new filename.

* Make the required changes in the new window `.rs` file:

** Adjust the content of `title()`, `view()`, `new()`/`try_new()`, `display` as required.

** If required add a `Message` enum, and `update` function. See existing `preferences.rs` for an example.

* In `window.rs` add the new filename.

* In `src/application/session.rs` add any other session data needed to be saved.

* In `application/application.rs`:

** To `use crate::{ ... window::{` statement add the new window filename.

** If new window has its own `Message` enum, add it to `Message` enum, to be able to pass messages to the new window's `try_update()` method.

** To `try_update()` method, add match branch for new window, either directly to window's `try_update()` method, or if needing to do more logic outside of window's `try_update()` method, in the new window's rust file can add a `update_?` function, where ? is the window abbreviation. See other branches for examples.

* In `src/application/enums.rs` add entries to both `WindowType` for the window and `StringGroup` for the localisation.

* If new window is accessible from the application's menu bar then add entry in `window/main/menu_bar.rs` and add match branch to `update_main()` function to handle the displaying of the new window.

* In the `src/localisation/` directory, copy an existing string group file, rename and edit the content.

* In `src/localisation.rs` add the new filename.