Original Developer S Notes and Errata at Time of Acceptance

The MonoDroid (Android) Version of the Driller’s Toolkit

Original Developer’s notes and errata at time of acceptance Version 2

F. Scott Deaver

January 4, 2013

2Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Introduction The Drillers’ Toolkit for Android application provides access to a number of standard drilling calculations (currently 42 in number) on the Android mobile platform. The design is intended to provide a uniform user experience across all calculations while respecting Android development guidelines and standards and while maintaining consistency with the Drillers’ Toolkit implementations on other platforms (notably iOS).

The development of this application faces challenges that are different from those faced on other platforms, due in part to the use of the relatively new MonoDroid development environment, the number of third-party tools and component required from diverse vendors, the nature of open-source development (from which Android originates), the explosive evolution of mobile computing, and a paradigm for development (emphasis on “activities” with state information conveyed by “intent” events rather than reliance upon an overarching application container) that varies from both traditional Windows and iOS conventions.

This documentation addresses the design, the implementation, and the known development errata that were in play as of acceptance of the development work and demonstration by Halliburton Landmark principals on January 4, 2013.

User-facing elements and behaviors

Intended work flow For any given calculation starting from the startup of the Drillers’ Toolkit application for Android, the ordinary workflow would look something like this:

The solid lines represent the normal pattern of usage, and the dashed lines represent optional paths the user may select. The options and inputs activity screens will supply default values for all editable/selectable fields, and the user can skip entering values if he/she so chooses. It is possible – though not useful or likely except for testing purposes - to go through the options and input screens without entering any custom values and still generate calculation results.

Elements common to all activity screens The activity screens for the Drillers’ Toolkit application for Android share common elements, some dictated by compliance with Android development guidelines, and some provided for consistency with Drillers’ Toolkit applications on other platforms.

Device versus emulator elements The screenshots provided here are from the Android emulator that is part of the Android SDK (provided by MonoDroid as a convenience when MonoDroid is installed). The emulator display contains the view as shown by the device inside a container that represents a generic representation of the off-screen device controls.

Device display What the user sees on the display screen of the device is shown here inside the purple square:

4Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Emulator generic device controls That portion of the screen shot that represents the generic device controls is shown here (again, inside the purple square):

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 5 Emulator hardware “back” button Of the emulator’s device generic device controls, the one we are most interested in is the back button, shown here inside the purple oval:

6Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Device display common elements A typical Android activity screen (in this case, the calculation selection activity screen) would look like this:

8Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 “Up” chevron All activity screens except the topmost screen (which in our case is the calculation category screen, shown below) will have a standard “up” chevron in the action bar (note that this widget behaves differently than the device’s hardware back button, as described below in the section on navigation):

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 9 Application icon All activity screen action bars will contain the Drillers’ Toolkit mobile application icon:

10Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Activity title or application name All activity screens will show the activity title, with the exception of the topmost screen which will display the Drillers’ Toolkit application name instead:

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 11 Settings menu item for top two activities The two topmost activity screens (calculation category selection and calculation selection, respectively) will display a settings menu item (used to select the units system and in the future, potentially other configuration options) – this option is, by design, not presented once the user has entered the calculation inputs, options, or outputs activity screens:

Elements common to input and output activity screens The input and output activity screens each contain rows of widgets, consisting of a display label for a value, an edit control for entering (in the case of the input activity screen) or viewing (in the case of the

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 13 output activity screen) a value, and a spinner control for selecting the desired unit of measure from a list of measures appropriate to that value as prescribed by the selected units system:

Last-value retention Once a calculation has been exercised, the last values of the option selections (if any) and the last values of the input parameters are retained (for inputs, in combination with the last unit of measure chosen for

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 15 that parameter). Whenever that calculation is re-entered, regardless the number or type of intervening calculations performed, the options and inputs for that calculation will be set to the last-used values.

Navigation There are several means by which the user can navigate back and forth between activities – in certain situations, navigation is automatic as the result of a selection in a widget or control.

Up and back Backwards and upwards navigation is done through the action bar “up” chevron (if present) or the device’s hardware “back” button. Each of the two methods has behaviors that are different from the other. When the current activity is not the topmost calculation category selection screen, the “back” button returns to the most recent activity screen displayed. When the current activity is the topmost calculation category selection screen, the “back” button closes the application, per Android guidelines.

The action bar “up” chevron in some cases will behave as does the back button, but its intent is to navigate back to a previous level of activity, rather than to the most recent activity screen. If you are in the topmost calculation category selection screen, the up chevron is not displayed, since that is the uppermost level. If you are in the settings activity screen, the up chevron returns you to the most recent activity screen, as does the back button. If you are in the calculation selection screen, the up chevron takes you to the topmost calculation category selection screen. If you are in any of the options activity, input activity, or output activity screens, the up chevron will take you to the calculation selection screen.

Forward Forward navigation behavior varies by screen and situation – note that you cannot move forward from the output activity screen, since it is the last activity in the chain (use the up chevron or back button to navigate from the output screen).

Automatic Forward navigation is in some cases automatic (specifically, when there is nothing else you could do). If you are in the calculation category selection screen and choose a calculation category, you will automatically be taken to the calculation selection activity screen. If you are in the settings activity screen and select a units system (even if it is the same one selected upon entry), you will be automatically taken back to the previous activity screen (which is the same behavior exhibited by tapping the up chevron or back button). If you are in the calculation selection screen and select a calculation, you will be automatically taken to either the options activity or inputs activity screen (whichever is appropriate to the calculation type you selected).

User-selected For other activity screens, the user must do something specific to navigate forward. If you are in the options activity screen, a “continue” button will be presented, and you’ll need to tap that button to move forward. If you are in the inputs activity screen, a “results” button will be displayed, and you’ll need to tap that button to move on.

16Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Startup appearance Upon initial startup of the Drillers’ Toolkit application for Android, the calculation categories selection activity screen is presented (see description below). Subsequent calculations can be initiated from any one of the subordinate activity screens (with the exceptions of the settings activity and outputs activity screens), and it is not necessary to return to the startup screen unless a calculation from a different category is desired.

Calculation categories selection activity screen This is the topmost activity screen of the Drillers’ Toolkit for Android application, and allows the user to select from various groups of available calculation. No “up” chevron is presented in the action bar, and tapping the hardware back button will exit the application. Selection of any category will automatically advance to the calculation selection activity screen:

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 17 Calculation selection activity screen From this activity screen the user can select from among the available calculations associated with the pre-selected calculation category. Upon selection of a calculation type, navigation will automatically proceed to either an options activity or inputs activity screen, as appropriate for the selected calculation type:

18Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Settings activity screen (units system selection) The user can elect to change or view units systems settings from either the calculations category selection activity screen or the calculation selection activity screen. Once a unit system is selected, navigation automatically returns to the previous activity screen:

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 19 Options activity screen For calculations that have options selections that affect later input choices or default values, the options activity screen will be presented – options are displayed spinner (aka, “combo box”) controls that allow the user to select one from a list of dropdown options:

20Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Inputs activity screen The inputs activity screen allows the user to view and/or edit the parameter values that will be passed to the calculation. Tapping the “Results” button starts the calculation:

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 21 Outputs activity screen The output activity screen allows the user to view calculation results, and potentially display those results in different units of measure:

22Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 23 Programming issues and considerations

Build environment considerations Currently, development of the application is done using MonoDroid unlicensed free download version 4.4.54, the version of the Android SDK supplied by that download (though the Android SDK – most importantly, the emulation libraries - will update itself independently with its own updater), the most recent version of ActionBarSherlock (which unfortunately does not yet report its own version), and the latest version of, and updates to, Microsoft’s Visual Studio 2010.

I cannot emphasize enough that this is an extremely fluid development environment – updates and changes to any one of the components, whether intentional or not, can (but do not always) have a significant (and potentially frustrating) impact on the output work product. I have created some rules of engagement, as expressed below, which have helped me manage and be successful in this environment.

We have archived the ActionBarSherlock source code in the “ThirdParty” section of the source code repository because we cannot determine version. From time to time, the latest version of that code should be downloaded, tested against our other build components, and (if successful) the old ActionBarSherlock code should be replaced with the new code.

We have not done the same with the Android SDK or the MonoDroid environment in part because the emulator support we need for devices in included in those and is updated on a nearly-weekly (sometimes even every other day) basis and these updates are essential because of the bug fixes they include. As we do with Visual Studio, we trust the vendor to manage these updates reliably.

Project creation in Visual Studio 2010 only For the moment, Android projects MUST be created using Microsoft Visual Studio 2010. The current code will not compile and run successfully using Visual Studio 2012, and you must not use iOS or MonoDevelop to create new projects within the Android application solution. I strongly advise against using MonoDevelop at all, despite the fact it does have useful UI layout and design functionality, because of the danger of accidentally saving into the *.csproj files. If you must use MonoDroid, make a copy of the build environment, use MonoDevelop in that copy, and then manually copy the desirable resulting source code fragments into the original project files.

The issue here is that the problems caused by Android project creation using MonoDevelop or iOS are subtle and will consume big chunks of debugging time trying to run them down. Please benefit from my experience and stay within the VS2010 build environment.

Calculation and units library build anomaly

.Net versus MonoDroid frameworks issue The MonoDroid framework is based in large part on the .Net framework, but is sufficiently different that currently within Visual Studio 2010 you cannot bind a .Net-based project that produces an assembly into a project that is MonoDroid-framework-based. You can bind the binary file produced by .Net project into the MonoDroid-based- project, but not the .Net project itself. Of course, when you bind the binary

We have two libraries (Calculations and Units) which are produced as .Net assembly projects to be used by several other non-MonoDroid applications (notably Drillers’ Toolkit applications on the iOS and Windows Phone platforms).

Shadow project workaround For our final release build of the Android application when the time comes for distribution, we will want to simply bind the Android/MonoDroid project to the binary .Net assembly output files. However, to enable debugging during development, I have created two shadow projects for use only by Android – Calculations-Android and Units-Android – that point to the source code files within the base Calculations and Units .Net projects but which wrap them in MonoDroid (rather than .Net) platform projects. Although it is something of a hassle to keep the pairs of projects in sync (though not so much for the Units library, which is stable), this approach allows us to debug into Calculations library source code easily and reliably from Android.

Manually editing the Calculations-Android.csproj file Among the many deficiencies in the Visual Studio 2010 C# projects support is the forcing of copies of, rather than references to, source code files when adding existing source code files to projects using the IDE. To get around this, you’ll need to manipulate the shadow project files manually.

We’ll use the Calculations-Android.csproj as an example, since it is by far the most likely to need changing. When in the IDE you see source code files that are new in the Calculations project, copy and paste those into the corresponding Calculations-Android locations as you normally would. You will note that the icons for the source files you copied will look like this: , rather than like the other icons

(representing source file references that existed prior to your additions), which look like this: .

Save your work, and exit Visual Studio 2010. Using Windows File Explorer, find the file(s) that was/were copied into the Calculations-Android project’s file folders, and delete those files (do not delete the files from the Calculations project!).

Using Notepad.exe, open Calculations-Android.csproj for editing. Find the line(s) that contain your new file names, like this:

Change the line that reads ‘’ to instead read ‘’. Do this for all of the files you added – what we want to achieve is to include the original source files for the Calculations project in your Calculations-Android build, rather than including local copies.

Save the Calculations-Android.csproj file, taking care not to make any other changes.

Now reload the Android application solution into VS2010. If everything went correctly you should now see links to the original Calculations project source files (symbolized by the icon) in the IDE’s file list for the Calculations-Android project, rather than copies of those files.

As noted above, the Android-only shadow projects for the Calculations and Units assemblies will be required for debugging. However, for our final release build of the Android application when the time comes for distribution, we will want to simply bind the Android/MonoDroid project to the binary .Net assembly output files.

VS 2010 updates and dependency releases affecting build environment If you’ve built a stable set of source code files successfully in a previous session, and find that a fresh build attempt against the same set of source files no longer builds or runs correctly, after eliminating the usual suspects (too much wine the night before?), you’ll want to investigate any changes to these four elements as described in the following sections.

VS 2010 Although automatic updates to VS2010 rarely cause problems to standard project types, the MonoDroid plug-in is highly sensitive to changes. The plug-in itself can be removed inadvertently by an update, or a compatibility issue can arise between the MonoDroid components and a new Visual Studio library version. Generally speaking, I’ve found the easiest solution to be uninstalling MonoDroid, and re- installing the last version of MonoDroid that I installed myself. If that doesn’t solve the problem, I uninstall MonoDroid again, download the latest version of MonoDroid from the MonoDroid website, and install that version. To this point, one of the two re-installs has always resolved the issue.

MonoDroid See the notes for VS 2010 above.

Android Android regularly updates their SDK, especially the emulators. I run the Android ADK emulator manager frequently (always adding any new components that are shown as missing), and update whenever I am prompted to do so by the Windows O/S update messenger.

26Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 ActionBarSherlock We keep a copy of the ActionBarSherlock code in our repository. There is no reliable versioning attached to the source code as of this writing, so periodically I bring down the latest version into a fresh copy of the Drillers’ Toolkit Android solution, test it thoroughly there, and then add the source to the repository if there are no issues with it.

Design and compatibility considerations

Multiplicity and variety of Android devices We did not have the capability (nor was it in the statement of work) to run the Android application on any actual devices, in part because we did not obtain a formal license in time from MonoDroid that would allow us to publish to the Google app store. We know from testing on various device emulators there are a number of minor cosmetic issues on certain devices, and we suspect some percentage of these are from bugs or anomalies in the emulators themselves. I do not think it is possible or desirable to attempt to achieve perfection on any one device or even family of devices, but certainly we would want the best possible appearance and performance over the largest number of devices.

That is, however, a bottomless pit, and some management input is going to be required to affix how much time and focus should be allocated to the problem. I’d suggest working towards publishing some kind of corporate standard for mobile device appearance and performance (perhaps tied in some way to a more stable platform with fewer devices, such as iOS), and then making sure developers adhere religiously to that standard.

Relative versus fixed user components issues There is an order-of-magnitude difference in developing for the Android platform over other platforms because on Android relationships between visual display components in most cases must be described referentially rather than literally simply because of the sheer number of different devices, vendors, aspect ratios, CPUs, screen sizes, resolutions, and even pixel intensities (screens that wash out in daylight versus Amoled technologies, for example). In other words, you cannot say “Position a control of X pixels in height Y pixels from the boundary of control Z” because every consumer of that common code will produce a different result. Instead, you have to say “Divide the actual display width (whatever it happens to be at runtime) into four quadrants and center a text box sized to the display of string X into the first quadrant”. While the results displayed on different devices will still have differences in their appearance, the second statement will produce more similar displays across a greater number of disparate devices. iOS developers, on the other hand, have a small subset of devices rigidly controlled by a single vendor to very precise dimensions and qualities (known and published even before production of those devices), and so can very accurately position elements on a screen, and can afford to write device-specific escapes if necessary.

We cannot, therefore, simply port UI elements from other platforms. It would be nice if we developed our own drag-and-drop editor for developing to a pre-defined corporate standard (I am not proposing

Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 | User-facing elements and behaviors 27 that anyone do such a thing, I am just saying that having that kind of editor would be nice). Even if such a tool existed, challenges would remain. Currently, MonoDroid and/or the underlying Android Java code have significant issues in their own layout managers and algorithms. We have places in our code where we do want to dictate specific sizes of things (font size, spacing between text and a neighboring icon, for example) and the relative positioning of items requires a lot of code very sensitive to small changes. When and if you do code a specific value for a size in the UI, it is difficult to understand or manage how the layout manager in Android is going to respond to that value in combination with the referential positioning decisions it must make. It appears in many cases the layout manager simply discards hardcoded values.

That’s the bad news – the good news is that MonoDroid is a new and popular development environment, and as it grows, more and more developers will be faced with the same issues. There is no doubt that eventually one of them, or MonoDroid itself, will come up with a workable solution (the closest thing to a visual editor out there now – DroidDraw – is famously and laughably incompetent). A decent editor should be possible which would allow you to drag and drop components, and then link components to one another with referential (rather than hardcoded) placement relationships, in the same way that Vision allows connectors to maintain their points of contact while moving connected objects around.

Bottom line: As a developer whose been around since the invention of dirt (smile), I’d caution anyone against devoting a lot of code to working around these problems unless absolutely necessary, and if possible to wait until MonoDroid and/or Android sort them out on a bug fix or new version release.

Unfinished business

Units conversions There is a small design error in the way units conversions are handled that affects only the input activity screen. When changes occur in an input edit field, I originally decided to store both the new value and its units of measure as a “last known value” pair – my thought was that I could reduce or eliminate all of the unit conversions back and forth along with the “units creep” that occurs with multiple conversions. It generally works quite well. However, the same code is being hit as a result of a textbox contents change regardless whether the changed value was entered by the user or occurred as a result of a units conversion caused by a units change. As long as the change was a value change by the user, things are great. However if the user instead was changing to a larger unit of measure, then the new value at the new unit of measure gets stored as the last know value pair. If the user then returns to the old unit of measure without having entered a new base value, he/she will have lost the precision of their original entry. For example, say the user originally entered “11.11” as millimeters. They then convert to meters, displayed as “0.01”. Now the user converts back to millimeters, and they get “10.00”.

This is very easy to fix – simply retain all last-known values (but only those changes directly entered by the user) in base units, and always make the conversions for display up and down from the last user- entered value (again, expressed as base units) – but I didn’t realize the design error until the moments just before the final demo, and I didn’t want to take the risk of making the change then.

28Introduction | Halliburton Landmark – CONFIDENTIAL AND PROPRIETARY © 2013 Device-dependent tweaks When we are able to install the release build onto actual devices, there are going to have to be tweaks added to accommodate vagaries in some of those devices. This is going to be a device-by-device, situation-by-situation, and probably largely experimental effort.

Calculations supported At the time of acceptance, there were forty-two calculations in the calculations library that had been tested and debugged through the Android application described above. This is the complete list of calculation categories and calculations that were tested: