iced_af

= {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 Results 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 consts 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.