Table of Contents BCheckbook Notes Known issues Version History Questions Usage Searching Records Removing Records Setting Categories Saving & Loading Importing QIF Files Importing TSV Files Backing up Data Transferring Data macOS Destination from iOS iOS Destination via AirDrop Support Contributing Other Projects Used

BCheckbook

iOS Version: 1.2.6

macOS Version: 2.0.1

Author: Bryce Campbell

Copyright: 2021

Description: A simple checkbook ledger that can be used to keep track on finances on your computer and on the go without an Internet connection.

License: See LICENSE

Notes

This application has only been tested on macOS 13 and iOS 16.

Known issues

Exports from macOS not getting imported on iOS

Status is currently unknown, but has been recently brought to my attention.

After seeking help elsewhere, it is suspected that there might be issues with the database on iOS, due to what the user has provided when reporting it.

With this possibility in mind, try either downloading a copy of the database from the repository, located in the Shared folder, or copy your database from the location specified in this README over to the iOS app's Documents folder.

I cannot guarantee it will fix things completely, but it should tide things over for a bit.

Issues importing on iOS 17

After updating to iOS 17 (iPadOS 17 on iPads), sharing via Air Drop does not automatically import data to app.

Upon investigation into the matter, it looks like Apple decided to change how Air Drop works, including not displaying a list of applications registered as supporting the format, for security reasons.

Until Apple changes its mind or implements a better way to achieve the same goal, it is best to exchange data via iTunes File sharing, which has built in support in Finder on current versions of macOS, if you are sending data to your phone or iPad.

Please note that some conveniences I provided may not work because the importer expects extensions to match exactly, so TSV files that the app creates when using the share button must have the tsv extension.

Version History

1.3.1 (iOS)

Minor Update

Update UI code to remove deprecated code on iOS 17.

Released December, 6, 2023.

2.0.1 (macOS)

Minor Update.

Add TSV support to app.

Please note that this version requires macOS 13 or later due to underlying code that uses stuff only available in that version and later, although functionality has not changed.

Released June, 6, 2023.

1.3 (iOS)

Minor Update

Add support for TSV and the capability of sharing data directly from app.

With the implementation of that latter, it is no longer necessary to use the Files app to transfer data.

Released June 6, 2023.

1.2.5 (iOS)

Minor Patch

Fix decrepated code and have main view on iPad display transactions.

This update is only available on iOS 16.

Released November 11, 2022

1.2.4 (iOS)

Minor patch

Categories that users add when selecting a category are now automatically selected.

Released July 31, 2022

2.0 (macOS)

UI modification, to make the UI look and act more like how it was intended, including the ability to delete either just one of multiple transactions.

Due to the changes made, the application no longer autoscrolls to new entries.

Released July, 22, 2022.

1.2.2 (macOS)

add autoscroll to new item to macOS app, to allow it to operate like iOS app.

Released June 25, 2022

1.2.3 (iOS)

Make app autoscroll to new item, making it quick and easy to modify new entry.

Released June 24, 2022

1.2.2 (iOS)

UI tweaks

change add button&39;s label to a system provided image, making it easier to add transactions, and make Record views display details vertically, which fixes things getting cut off.

Released April 4, 2022

1.2.1 (Both)

Bug fix

fix bug that occurs when trying to export to a bcheck file, by merging BCheckFileDocument and QIFDocument, making only one fileExporter() instance necessary.

Released March 13, 2022.

1.2 (Both)

Minor update

Data loading is now asynchronous, due to added support for importing and exporting QIF</a>, which can add massive amounts of records.</p>

released March, 8, 2022

</dd>

1.1.1 (Both)

Minor Patch

Importing now updates existing records, in addition to adding new records.

1.1 (Both)

Minor update

Allow user to search for transactions, allowing them to get transactions from certain vendors and/or categories.

This update is only available to iOS 15 and later and macOS 12 and later, due to API availability.

1.0 (Both

Major change

Add view that allows person to get a quick overview of transactions, which actually makes categories useful and make some code changes to reduce redundant code.

Released January 13, 2022

0.3.1 (Both)

Minor patch.

Take care of remaining known issues by changing how balances are retrieved.

Released January 2022

0.3 (Both)

Major change, such as:

• move to a database backend
• Fix issues in mac UI and change mac UI a bit
• transactions can be placed into categories
• transactions can be imported and exported (helps with migration)
• iOS app now registered to accept bcheck format
• Move extension code from mac code to shared

Relesed December 2021.

0.2 (Both)

Major fix that deals with updating suceeding transactions, fixing transaction ordering, and showing the proper amounts. Released Nov. 19, 2021

0.1.1 (iOS)

Minor patch that gives user feedback if the save was successful. November 2021

0.1 (Both platforms)

Initial release. July 2021

</dl>

Questions

1. Why create this application when there are so many other applicatios that do the same thing?

   At the time of writing this README, I have been using GnuCash to keep track of finances and I wanted something that could be utilized to help keep track of that on other devices.

   In that that time, I tried looking for something kind of like GnuCash for Android, so I could just transfer my transactions easily and came up empty, or finding apps with features I did not need, such as multiple accounts and charts.

   In light of the situation, and to challenge myself further, after coding my own implementation of Yahtzee in Swift using SwiftUI (application is not available anywhere at this time), I decided to make this app myself.

2. Can I import my transactions from X?

   When I initially wrote this program, this was not possible, and while I still kind of I stand by my reasoning for CSV support, I decided I should support at least one more common format, in case a family member who I know uses Quicken switches to my app.

   As such, it is possible to import transactions from QIF files, but it is limited in comparison to what the Quicken Interchange Formart allows, especially because this app does not support multiple accounts, nor does the library I use, as all nonivestment and noninvoice transactions are grouped together (e.g. all Bank transactions are listed together regardless of account).

   For best results, I recommend starting off anew than trying to import via QIF.

3. Can I pull data in from my bank account?

   I might implement this in the future, but this application cannot do that at this time. I understand that it is a neat feature and something that may be considered a must for apps dealing in finances, but because some banks are either ditching OFX or only allowing certain entities access via OFX, GnuCash was unable to do online banking and many such banks want people to use their APIs instead.

   If I am in a position to investigate these APIs, seeing as there might be some cost involved, I may look into the details and see how they relay the data, as figuring out those patterns would be easier than trying to deal with user habits that make importing from applications like GnuCash difficult.

Usage

The program is simple enough to use, aside from quirks that cropped up because of the different UI schemes utilized for macOS and iOS. However, one thing shared in both versions is that the dollar amount will not be recorded until pressing enter. This is something one must live with for now because it does not seem to be possible have the fields displayed as currency and to automatically register the correct value. Also, the currency symbol is required when inputting those values, though they are omitted in the JSON exports and database.

Searching Records

Starting with version 1.1, it is possible search records in the ledger. However, this feature is quite limited. It is only possible to search under two different citeria, which are the vendor and the category. While I have thought about including other things in the search criteria, it seems to be a little complex for me to get the values necessary from the user, so I decided to simplify things to only two particular values. If you want to search for a vendor, you just type in the name like this:

Fake Street Electronics

To look up transactions in a particular category, you would type in:

category&amp&#59;&#35&#59;58&#59&#59; gifts

Spaces are mandatory after the category prefix, due to the pattern utilized to deal with category queries. To look up transactions with a particular vendor in a particular category, you would type:

Fake Street Electronics category&amp&#59;&#35&#59;58&#59&#59; gifts

all text in a query, except for prefixes, like category, are case insensitive, so the category specified is case insensitive, as is the vendor.

Removing Records

Records can only be removed from the ledger view in one of two ways, depending on where you are using the app:

• Swipe to Delete (iOS only)
• minus button (as of version 2.0 of the Mac app).

Records can also be removed from the ledger in search results in the same fashion.

Setting Categories

Setting categories, like removing records, is a little different, depending on your platform.

On iOS, after telling it to set a category, you can select a category from a list or filter the list and add new new categories via the filter field that is presented via a custom picker view.

On macOS, a combo box with autocompletion is used and if you type in a category that does not exist in the database, it should add it upon pressing enter, otherwise autocompletion will try to guess what you want.

Saving & Loading

At this point in time, the Mac and iOS versions are fairly similiar in the area of data persistece.

Both utilize a database stored as register.db and will automatically save changes to the database.

As such, there is no need to manually load data in either version of the app.

Importing QIF Files

Although this app supports importing and exporting QIF files, as of version 1.2, there are some limitations.

The most important to note, aside from the fact that they cannot be used to update existing entries, is this app only imports things under the !Type:Bank heading.

While the library I am using will also pull in stuff marked Cash, CCard, Oth A, and Oth L, Bank is the only one accepted because this application was only ever meant to track one account.

Also, all dates must be in MM/DD/YYYY format. This is a limitation of the library used and is the only format I chose to accept.

Any transactions not in MM/DD/YYYY format will not be seen, thus will not be imported into the application.

Importing TSV Files

Although this app supports TSV files, the items in the TSV file are expected to have no less than 8 columns and no more than 9 columns, which are read like this:

Column 1

Identifier

Column 2

Date

Column 3

Check Number

Column 4

Reconciled

Column 5

Category

Column 6

Vendor

Column 7

Memo

Column 8

Credit Amount

Column 9

Withdrawal Amount

The date must be in YYYY-MM-DD format to register correctly and the Reconciled column can only have either an N or Y. Failure to follow these rules will result in the record not being loaded.

Also, only one of the final two columns is allowed to have a value and both are expected to be formatted like your typical currency without any currency symbol.

The contents of your TSV file should ultimately look similiar to this:

FF04C3DC&amp&#59;&#35&#59;45&#59&#59;F0FE&amp&#59;&#35&#59;45&#59&#59;472E&amp&#59;&#35&#59;45&#59&#59;8737&amp&#59;&#35&#59;45&#59&#59;0F4034C049F0	2021&amp&#59;&#35&#59;45&#59&#59;07&amp&#59;&#35&#59;45&#59&#59;08	1260 	Y	Opening Balance	Sam Hill Credit Union	Open Account	500.00	
1422CBC6&amp&#59;&#35&#59;45&#59&#59;7B0B&amp&#59;&#35&#59;45&#59&#59;4584&amp&#59;&#35&#59;45&#59&#59;B7AB&amp&#59;&#35&#59;45&#59&#59;35167CC5647B	2021&amp&#59;&#35&#59;45&#59&#59;07&amp&#59;&#35&#59;45&#59&#59;08		N	Gifts	Fake Street Electronics	Head set		200.00
BB22187E&amp&#59;&#35&#59;45&#59&#59;0BD3&amp&#59;&#35&#59;45&#59&#59;41E8&amp&#59;&#35&#59;45&#59&#59;B3D8&amp&#59;&#35&#59;45&#59&#59;8136BD700865	2021&amp&#59;&#35&#59;45&#59&#59;07&amp&#59;&#35&#59;45&#59&#59;08		N		Velociraptor Entertainment	Pay Day	50,000.00	

While all three records have identifiers, no value is required to be in that column.

To make this easier, it is recommended to use either Microsoft Excel or LibreOffice Calc or something like those two programs to create or edit TSV (aka. tab separated value) files, rather than do it by hand.

Backing up Data

Due to the iOS app and the Mac app being a bit more similiar, with the recent changes, there are two ways to back up data.

• backup the database file
• export transactions to a bcheck file
• export transactions to QIF (starting with version 1.2)
• export transactions to TSV (starting with version 1.3 on iOS and 2.0.1 on macOS)

Of the four options, the latter three are recommended for most people, as the database structure might change in the future, and the latter most two should allow you to migrate to other applications if desired.

However, if you wish to back up the database or access it, it can be found in one of the following places, depending on platform:

• Application's Documents folder (iOS app)
• me.brycecampbell.bcheckbook folder somewhere in your user's Library folder (macOS app)

Of the two most recommended options, bcheck and TSV</abbr> will provide the best experience, because everything is always imported with QIF and there is no way to use them to update existing records, whereas bcheck and TSV files provide enough data to update existing transactions.</p>

Transferring Data

As stated above, the iOS application and macOS application work similiarly in terms of data persistence. You can either transfer the database, import a bcheck file, or import a QIF file. While all transactions will not be loaded every time, like the initial versions, when importing a bcheck file, it will update any existing listings in addition to adding new transactions as of version 1.1.1, making deleting the database unnecessary.

macOS Destination from iOS

You can use either Airdrop inside the Files app or use either Finder or iTunes to grab the exported bcheck file. When the transfer is made via AirDrop, your file will be located in the Downloads Folder, while Finder, and likely iTunes may be more flexible.

iOS Destination via AirDrop

As of version 0.3, the iOS app is registered to accept files bcheck directly.

When transferring a bcheck file via AirDrop, the application will import any new transactions into the database, update existing transactions, and update the list of transactions.

However, if you want to reimport everything, to start things with a clean slate, delete register.db, after closing the application, and then try importing your data, as the app should regenerate the database.

Support

If you have any problems, I will try my best to help you. Depending on where you are seeing the problem, send me an email at either of the following:

ios@brycecampbell.me

mac@brycecampbell.me

Use iOS email for issues that only exist in iOS and the Mac email for issues that only exist in the Mac app.

If the problems exists in both versions, choose ether one and be sure to note in the subject that it is both systems, otherwise I will assume the issue is only on the platform associated with the email you used.

Contributing

If you are familiar with Swift and SwiftUI and want to help make things work even better by fixing issues or adding things, feel free to fork this project and submit a pull request.

Submissions will be tested by me before they will be merged.

Other

Starting with iOS app version 1.3.1, the app only works on iOS 17 and later.

If you have iOS 15, version 1.2.4 is the last version available, and if you have iOS 16, version 1.3 is the last available version.

Projects Used

This app uses the following projects to help things run smoothly.

SQLite.swift

Used to implement the database backend of the application.

ComboBox

Custom view that is used to allow users to either add their own categories or to select from the list of available categories.

QIF

Custom library used to parse and export QIF files.

Swift Identified Collections

Library to help create bindings just by specifying id (macOS version only).