Overview of Code Structure

See also "Code Methodology and Dependencies"

Each user-interface page in a WinStore app is represented as a XAML (.xaml) and corresponding C# (.cs) file. These together define an object class for each page and its layout. The XAML is mostly but not exclusively about layout; the C# is mostly but not exclusively about behavior.

Suggested reference for new WinStore developers:

• Charles Petzold, "Programming Windows, Sixth Edition" (or later), Microsoft Press

During Startup

• Splash screen defined by manifest.
• "ExtendedSplash", which adds a progress ring
• "StartupWizUserControl" - Appearing only when the app is first run after install, it shows a full-width dialog, overlaying the extended splash, that asks for the user's username, password, and organization, as known at TriageTrak. This is invoked if, after trying to read the cached UserAndVersions.xml file, no pre-existing username and password is available.

Main TP8 Navigation Pages

• "App". Main app, providing:

  • Global data structures, accessible throughout as "App."
  • OnLaunch initialization of foregoing, generally by interrogation of web services and caching results.
  • Structuring of Settings charm subpages (discussed further below)
  • Management of splash screens and startup/first-run wizard.
  • Startup of secondary non-UI thread to do "ping" polling of web service connectivity.

• "HomeItemsPage"

  • Top-level group view: Checklist, New Report, Outbox, All Stations, Statistics. (Each of these group items is also generally invocable by an app bar icon throughout.)

• "ChecklistPage". A simple page to choose which disaster event to report to, and a file picker to associate people with triage station roles.

• "NewReportPage". The workhorse page for new patient reports, with layouts tuned for portrait and various landscape modes.

• "SplitPage". Used to display Outbox and All Stations results. In full-screen or less-narrow landscape modes, there is vertically scrollable list to the left, with selected item details shown at right. In portrait mode or narrow landscape modes, these are 2 different pages.

• "ChartsFlipPage". Invoked by the "Statistics" tile on the home page. Can be flipped left/right to show 7 different pages, each of which has either 4 or 1 chart.

• "SearchResultsPage". Using the Search charm, with a string entered for name or patient ID prefix, and other filtering and sorting settings, results are returned as a thumbnailed multicolumn list. The list wraps at the bottom of the page, and (if too many columns to fit on the screen) may be flipped left and right.

• ItemDetailFlipViewPage. When a search is conducted, a list returned, and a particular result report is tapped, the view jumps over to this detail view of the report; one can also flip left & right through these reports.

• "ViewAndEditReportPage". Similar to NewReport in style, designed to view and potentially edit and resend a report.

• "WebcamPage". Invoked in several ways, but mainly by tapping the No Photo image box in New Report. Shows the camera view, allows capture and crop (done by an embedded control, with associated settings), then provides buttons to save, cancel, or retake.

Secondary TP8 Pages

Many of these come in "Flyout" and "NonFlyout" flavors. The content is meant to be the same, but the latter is needed to support windows 8.0-style snapped (narrow) mode, for which the flyout method didn't seem to work in the past.

• "FilterFlyout", "FilterNonFlyout". Sets advanced filters for Search Results (but not Outbox or All Stations, which have minimal simple filters instead.)

• "SortFlyout", "SortNonFlyout". Sets sort method (fields and direction) for Search Results, Outbox, and All Stations.

• Settings Charm Subpages

  • "SettingsFlyoutAbout". Just text and links.
  • "SettingsFlyoutCredentials". Enter and validate TriageTrak hospital staff username and password.
  • "SettingsFlyoutMyOrg". Select your hospital/organization/facility from those defined at TriageTrak, and show additional contact information.
  • "SettingsFlyoutOptionsCentral". Shows policy options fetched from TriageTrak, that are read-only at TriagePic.
  • "SettingsFlyoutOptionsLocal". Not many local options.
  • "SettingsFlyoutPrivacy". Just text and links.

Custom Controls

• ZoneButton. Use in NewReport and ViewEditReport to represent a zone button, with flexible coloring of background, smart coloring of foreground text.

• ZoneCheckBox. Similar to ZoneButton, but used in Filter.

UI Visual States

XAML works with a visual state manager, to allow layouts to adapt to available app real estate, a process known as "responsive design". The original 3.0 version of the app supported the four Windows 8.0 visual states:

• "FullScreenPortrait"
• "FullScreenLandscape"
• "Snapped" (landscape 320 pixels wide)
• "Filled" (landscape with remainder if another app is snapped)

In addition, within SplitPage (i.e., Outbox, All Stations), two "logical" visual states were defined. These were used when both the casualty person list and a selected record were presented side-by-side, rather than on separate pages. The two states represented either a loose or tight layout of those two columns.

During the move to Windows 8.1, it was decided to continue with the app-wide categorization of visual state (rather than categorize each screen independently), but with more categories. It was also decided to continue supporting 320 pixels as the minimum width, rather than 500. By TriagePic version 3.4, the categories (whose names can't start with a digit) are:

• "vs320Wide" (previously "Snapped")
• "vs321To500Wide" (narrow)
• "vs501To672Wide" (roughly half on a small screen)
• "vs673To1025Wide" (roughly filled on a small screen)
• "vs1026To1365Wide" (wide)
• "Over1365Wide" (wider)
• "FullScreenLandscape" and "FullScreenPortrait" (as before)

plus for SplitPage renamed logical states TwoColumnsLoose and TwoColumnsTight

Data Structures

The .cs files are grouped under the project's DataModel folder.

Data Structures Persisted as XML Files

The XML used is similar in spirit but not detail, to that found in TriagePic Win7. The XML files may be found in:

• C:\Users\ [myLogin]\AppData\Local\Packages\ [GUID for TP8]\LocalState where the GUID is a long string that is relatively stable for a developer, and typically contains the string "TriagePic". (Developer: once you track this down, make a desktop shortcut to this folder)

The method used to serialize/deserialize data structures to local storage uses generic Read/Write routines in DataModel/LocalStorage.cs (The result is less-elegant XML than that used by TriagePic Win7, which is coded quite differently. Thus the files are not designed to be interchangeable between TP7 and TP8, though conversion could be done with much manual effort). Structures and files using this method are:

• TP_OtherSettingsSource (OtherSettings.xml)
• TP_ErrorLogSource (ErrorLog.xml). See "Error Reporting" below for more about this.
• TP_FilterProfile (FilterProfiles.xml)
• TP_OrgContactInfoSource (OrgContactInfo.xml)
• TP_OrgDataSource (OrgDataList.xml)
• TP_OrgPolicySource (OrgPolicy.xml)
• TP_PatientReport. An object representing a single report, as seen in New Report or Edit Report.
• TP_PatientReportsSource. Provides both outbox and allstations lists of TP_PatientReport objects, as original, sorted, and filtered+sorted variants. The outbox original form is persisted as PatientReportsSent.xml. All stations, persisted experimentally at the outset, is now turned off pending a better model. (ReUnite caches all turning a session, then deletes... but scope may be different.)
• TP_ZoneChoices (ZoneChoices.xml)
• TP_UsersAndVersions (UsersAndVersions.xml) Mainly used as the place to save encrypted name and password. (This was shared for multiple users in the Win 7 model, but now pretty much for just 1 user, since each user gets a separate LocalStorage folder.)
• TP_EventsDataSource (EventsDataList.xml) Caches, with just a little mapping, a web service call that provides disaster short & long names, type (real or test), open/closed, and what roles can see. App adds url to icon for type too.

In some cases an internal data structure and persisted file is close to the format of a particular TriageTrak web service. In other cases they are quite different (sometimes because the web service has evolved) and much mapping is needed.

Additional folders and files found in this directory are generated by the Suspension Manager or the Dictionary process. Due to the TP7 lineage of TP8, XML files are used for persistence here, more than in other Win8 apps, which may favor the dictionaries or a local third-party database. Cloud storage is avoided as adding complications in light of HIPAA.

Data Structures for Web Services

As with TriagePic Win 7, the Service References/PLWS generates the client-side proxy code, which is interfaced to by intermediary functions in DataModel/LPF_SOAP.cs . The latter has similar functional coverage to Win 7, but (due to differences in the versions of Visual Studio used) has a different approach to in/out parameters.

Some functions involve JSON objects, and helper objects to serialize/deserialize these are in LPF_SOAP.cs. Additional mapping may be found elsewhere, particularly in TP_PatientReport.cs.

Other Data Structures

• TP_SendQueue represents an in-memory queue of reports waiting to be sent. This is not persisted (but probably eventually will need to be in order to support suspend/resume optimally).
• TP_SentCodeObj helps maintain, parse, and validate codes that indicate the send status of reports.

The above two items will also be found in TriagePic Win 7, though implementation is somewhat different.

Error Reporting

Among the data structures and their files listed above was:

• TP_ErrorLogSource (ErrorLog.xml)

As the name suggests, this provides functions to log errors (or warnings or other information). It is not yet called upon as much as the similar mechanism in TriagePic Win7; extend it as useful. For historical reasons, TP uses this method of error logging rather than generate application errors to the Windows Error Log. The code invokes it thusly:

await App.ErrorLog ReportToErrorLog(<message to log>,<message to user>, bool showToUser)

Both the first and optional second parameters are logged. The second parameter will also be shown in a popup dialog to the user if showToUser is true. This popup technique is not always applicable. Also, there may still be limitations in using this to report XML file handling errors, because of common code.

Currently, calls occur as follows:

• Informationally, during app startup: "FYI: Beginning or Ending App.Launch", "", false

• "During TP_EventsDataSource.ProcessEventList", "Invalid empty disaster event list", false
  Paired with a dialog to user:
  Could not connect to TriageTrak web service. Using previous information, cached locally, instead for:
  Disaster event list (actually, got list from web service but it was empty)

• In TP_PatientReport.cs:

  • "ERROR: [message from TriageTrak server]",
    "On Send or Resend - Patient report was not accepted by TriageTrak", true
  • "On Prep for Resend - for event with short name [eventShortName]",
    "TriageTrak can't find a record with Patient ID [id] associated with event [eventLongName]", true

• "From TP_PatientReportsSource.LoadNewPatientReportImage" or ".LoadNewPatientReportTextAndImage",
  "Bad image uri: [path]\nPatient ID: [id]", false

• "From SendQueue dequeuing", "X[number] as Send Status", false
  where [number] is 1-4. These are unexpected failure states.