calculator/docs/ApplicationArchitecture.md

Application Architecture

Windows Calculator is a C++/CX application, built for the Universal Windows Platform (UWP). Calculator uses the XAML UI framework, and the project follows the Model-View-ViewModel (MVVM) design pattern. This document discusses each of the layers and how they are related to the three Visual Studio projects that build into the final Calculator application.

---

Table of Contents

• View
  • VisualStates
  • Data-Binding
• ViewModel
  • PropertyChanged Events
• Model

---

View

The View layer is contained in the Calculator project. This project contains mostly XAML files and various custom controls that support the UI. App.xaml contains many of the static and theme resources that the other XAML files will reference. Its code-behind file, App.xaml.cs, contains the main entry point to the application. On startup, it navigates to the main page.

rootFrame.Navigate(typeof(MainPage), argument)

In Calculator, there is only one concrete Page class: MainPage.xaml. MainPage is the root container for all the other application UI elements. As you can see, there's not much content. MainPage uses a NavigationView control to display the toggleable navigation menu, and empty containers for delay-loaded UI elements. Of the many modes that Calculator shows in its menu, there are actually only three XAML files that MainPage needs to manage in order to support all modes. They are:

• Calculator.xaml: This UserControl is itself a container for the Standard, Scientific, and Programmer modes.
• DateCalculator.xaml: Everything needed for the DateCalculator mode.
• UnitConverter.xaml: One UserControl to support every Converter mode.

VisualStates

VisualStates are used to change the size, position, and appearance (Style) of UI elements in order to create an adaptive, responsive UI. A transition to a new VisualState is often triggered by specific window sizes. Here are a few important examples of VisualStates in Calculator. Note that it is not a complete list. When making UI changes, make sure you are considering the various VisualStates and layouts that Calculator defines.

History/Memory Dock Panel expansion

In the Standard, Scientific, and Programmer modes, the History/Memory panel is exposed as a flyout in small window sizes. Once the window is resized to have enough space, the panel becomes docked along the edge of the window.

Scientific mode, inverse function button presence

In the Scientific mode, for small window sizes there is not enough room to show all the function buttons. The mode hides some of the buttons and provides a Shift (↑) button to toggle the visibility of the collapsed rows. When the window size is large enough, the buttons are re-arranged to display all function buttons at the same time.

Unit Converter aspect ratio adjustment

In the Unit Converter mode, the converter inputs and the numberpad will re-arrange depending on if the window is in a Portrait or Landscape aspect ratio.

Data-Binding

Calculator uses data binding to dynamically update the properties of UI elements. If this concept is new for you, it's also worth reading about data binding in depth.

The x:Bind markup extension is a newer replacement for the older Binding style. You may see both styles in the Calculator codebase. Prefer x:Bind in new contributions because it has better performance. If you need to add or modify an existing Binding, updating to x:Bind is a great first step. Make sure to read and understand the difference between the two styles, as there are some subtle behavioral changes. Refer to the binding feature comparison to learn more.

---

ViewModel

The ViewModel layer is contained in the CalcViewModel project. ViewModels provide a source of data for the UI to bind against and act as the intermediary separating pure business logic from UI components that should not care about the model's implementation. Just as the View layer consists of a hierarchy of XAML files, the ViewModel consists of a hierarchy of ViewModel files. The relationship between XAML and ViewModel files is often 1:1. Here are the notable ViewModel files to start exploring with:

• ApplicationViewModel.h: The ViewModel for MainPage.xaml. This ViewModel is the root of the other mode-specific ViewModels. The application changes between modes by updating the Mode property of the ApplicationViewModel. The ViewModel will make sure the appropriate ViewModel for the new mode is initialized.
• StandardCalculatorViewModel.h: The ViewModel for Calculator.xaml. This ViewModel exposes functionality for the main three Calculator modes: Standard, Scientific, and Programmer.
• DateCalculatorViewModel.h: The ViewModel for DateCalculator.xaml.
• UnitConverterViewModel.h: The ViewModel for UnitConverter.xaml. This ViewModel implements the logic to support every converter mode, including Currency Converter.

PropertyChanged Events

In order for data binding to work, ViewModels need a way to inform the XAML framework about updates to their member properties. Most ViewModels in the project do so by implementing the INotifyPropertyChanged interface. The interface requires that the class provides a PropertyChanged event. Clients of the ViewModel (such as the UI), can register for the PropertyChanged event from the ViewModel, then re-evaluate bindings or handle the event in code-behind when the ViewModel decides to raise the event. ViewModels in the Calculator codebase generally uses a macro, defined in the Utils.h utility file, to implement the INotifyPropertyChanged interface. Here is a standard implementation, taken from ApplicationViewModel.h.

[Windows::UI::Xaml::Data::Bindable]
public ref class ApplicationViewModel sealed : public Windows::UI::Xaml::Data::INotifyPropertyChanged
{
public:
    ApplicationViewModel();

    OBSERVABLE_OBJECT();

The OBSERVABLE_OBJECT() macro defines the required PropertyChanged event. It also defines a private RaisePropertyChanged helper function for the class. The function takes a property name and raises a PropertyChanged event for that property.

Properties that are intended to be the source for a data binding are also typically implemented with a macro. Here is one such property from ApplicationViewModel:

OBSERVABLE_PROPERTY_RW(Platform::String^, CategoryName);

The OBSERVABLE_PROPERTY_RW macro defines a Read/Write property that will raise a PropertyChanged event if its value changes. Read/Write means the property exposes both a public getter and setter. For efficiency and to avoid raising unnecessary PropertyChanged events, the setter for these types of properties will check if the new value is different from the previous value before raising the event.

From this example, either ApplicationViewModel or clients of the class can simply assign to the CategoryName property and a PropertyChanged event will be raised, allowing the UI to respond to the new CategoryName value.

---

Model

The Model for the Calculator modes is contained in the CalcManager project. It consists of three layers: a CalculatorManager, which relies on a CalcEngine, which relies on the Ratpack.

CalculatorManager

The CalculatorManager contains the logic for managing the overall Calculator app's data such as the History and Memory lists, as well as maintaining the instances of calculator engines used for the various modes. The interface to this layer is defined in CalculatorManager.h.

CalcEngine

The CalcEngine contains the logic for interpreting and performing operations according to the commands passed to it. It maintains the current state of calculations and relies on the RatPack for performing mathematical operations. The interface to this layer is defined in CalcEngine.h.

RatPack

The RatPack (short for Rational Pack) is the core of the Calculator model and contains the logic for performing its mathematical operations (using infinite precision arithmetic instead of regular floating point arithmetic). The interface to this layer is defined in ratpak.h.