Albite Reader

Implemented features

• anti-aliased bitmap font in four sizes with over 850 glyphs, including latin, cyrillic and greek
• hyphenation for 29 languages
• 23 character encodings, including UTF-8 and most of ISO-8859 and Windows-125x
• animated touch-guided scrolling
• horizontal and vertical scrolling
• on-touch dictionary look up
• units conversion: temperature, length, area, ...
• portrait and landscape view
• images and basic styling
• color profiles
• portable book settings
• bookmarks
• table of contents

For more detailed information, have a look at the more comprehensive feature list or the tutorial.

System requirements

Download

As devices abilities can differ so much in the mobile world, it's necessary to make several versions of the same app, each one being targeted at a different device group. You should try to choose the group that matches your device capabilities best.

Your phone can install apps only over the internet? No worries, just visit the mobile site.

Want to download some older release? Then see all releases.

As the this app is developed by a single person, it has been tested on some very limited amount of devices. I'd be very grateful, if you share your experience with the app, so that I could fill in the list with more supported phones.

Installing the reader

It's installed like any other Java Mobile game. Just be sure you have the proper phone to install it, because not all AT&T, Verizon, or T-Mobile Samsung phones will be compatible.Transfer the jar file to your device, and then open it up from your phone's file manager. If that's not possible, you may need to download the app straight from you phone's web browser. You can easily do that, if you visit the mobile site.

Setting up security permissions

On most phones reading and writing files requires security permissions. Albite READER needs both: firstly, it obviously needs to read the book files, and, secondly, it needs to write per-book settings files that contain data about your book progress (including bookmarks). Therefore, if you don't grant permissions to Albite READER it will become impossible to use.

On some phones (e.g. Samsung GT-5230) you need to grant read and write permissions every time you launch the app. It's important that you select the option that will grant permissions and would not ask again during the the session or you might have to accept hundreds of requests. Such option might be titled Allow, ask once or Always allowed or Never ask. If you don't grand read permissions, you wouldn't be able to open books and the app would most probably close. If you don't give write permissions, your reading progress would not be saved.

Granting read permissions on a Samsung GT-5230	Granting write permissions on a Samsung GT-5230

On Nokia and Sony-Ericsson phones, you might be able to set permissions once and for all. Go to Tools, then App. manager, find Albite READER and set Read user data and Edit user data to Always allowed. The following screens are for another app, Smister, but the steps are the same.

Granting read permissions on a Nokia N95	Granting write permissions on a Nokia N95

Tutorial: Using the reader

First run

The first time you run the app you'll be presented with the license screen which you are obliged to accept if you are willing to use the app.

The license screen

After that, the file browser pops up and you need to browse to the folder where you put the books. Bear in mind that depending on your phone you might not be able to see some folders or even if you see them, you might still not be able to open your books because of security restrictions. So, you might need to experiment a little. It's highly probably that you might be asked to grant read and write permissions to the app.

The the initial state of the file browser screen	The file browser screen showing your books

After that the book loads up and you are ready to start reading!

Main screen

The main screen is the place you need to get most accustomed to for there you'll be spending most of your time. For the same reason, this screen is the most interactive part of the app and needs most explanations.

Firstly, you need to know that there are two screen modes: normal and full-screen.

The main screen in normal mode	The main screen in full-screen mode

The screen is most interactive when in normal mode. Let's see what separate areas it's made of and how they react to touch.

Areas according to what they are for	Areas according to how they react to touch

There are four touch interactions that the main screen responds to: press and release, press, hold and release, drag, hold and drag.

The area in violet is the toolbar. It responds to press and press and hold.

	Press and release brings up the main menu. Press, hold and release is a shortcut for quitting the app. Before quitting however, it will ask you to confirm your intention so that you wouldn't quit the app incidentally.
	Press and release brings the open book screen.
	Press and release brings the word look up screen. Press, hold and release brings the number conversion screen.
	Press and release switches the font size Press, hold and release brings up the font size selection screen.
	Press and release switches the day and night profiles. Press, hold and release brings up the color profile configuration screen.

The area in green is the way to switch pages.
Press and release on the left side scrolls to the previous page and respectively press and release on the right side scrolls to the next page.

Press and release on the area in blue switches between normal and full-screen mode (in the normal and HD versions) or opens the menu (in the Tiny and Light versions).

The area in yellow shows the progress in the current chapter.
Press and release brings up the table of contents.
Press, hold and release moves to the place in current chapter that corresponds to the point you pressed the progress bar.

The area in beige shows the number of the current chapter and the time.
Press and release brings up the book details screen, which shows book's title, its author and the language it's in.

The book content also reacts to touch.
Press, hold and release on a word (e.g. the area in red) brings up the word look-up screen.
Press, hold and release on a number brings up the number conversion screen.
Press and drag on the book content moves the pages according to your finger guidance.
Press, hold and drag enters into text selection mode. After release the add-bookmark screen would be shown.

Main screen in text selection mode

Key functions in the main screen

Downloading & installing dictionaries

Firstly download a few dictionaries. Then, you need to copy the dictionaries to their own folder on your mobile. Then select Set dictionary folder from the main menu and browse to the folder where you put your dictionaries.

The main menu with Set dictionary folder selected.	The dictionary browser showing the user is about to select the dicts folder.

Configuring your interaction with the reader

There a few options that setup the way you interact with the reader:

• Scrolling speed is the speed with which pages are being scrolled.
• Smooth scrolling makes scrolling looks more natural. It adjusts the speed so that it's not entirely constant.
• By default pages are scrolled horizontally. You can also scroll them vertically.
• The time needed to hold over an area to activate hold mode may be decreased/increased through the Long press after slider.

The page interaction screen.

Troubleshooting

I can't install the app on my phone

If you can't copy the .jar file to your phone, you'll need to download the app directly from you phone's web browser. Visit the mobile site from your phone and download the app.

After that you need to open the phone's file browser, navigate to the folder where you put the .jar file and open it. If the phone throws an error message, then you might not be able to install the full version, try with Albite READER Light or Albite READER Tiny instead.

I can't start the app

Well, there may be many reasons for that. Firstly, you need to accept the license that will show up the first time you run the app. After that you need to navigate to your books folder and select a book to open. Meanwhile you may be asked various questions regarding app permissions which you must accept or the app wouldn't work at all. What questions? Well, your phone may ask whether you'd allow Albite READER to read and write user data. And your books are user data. Finally, if the app closes unexpectedly or behaves in a funny way, you probably haven't got enough resources to run the full version. You should try Albite READER Light or Albite READER Tiny instead. You may also have a look at the system requirements.

Do I need to upgrade the app and how do I do that?

From time to time there may be new versions of Albite READER that fix some existing issues or add new functionality. Upgrading the app is easy. Simply uninstall it from your phone and install the new version exactly the way you did before. However, you'll may you app settings, i.e. you may need to set the dictionary folder again, setup page interaction and color profiles. The good news is that your book settings will be preserved as they are saved on the file system along with your books.

What are these .alx and .alb files along with my books?

See the section about portable book settings.

How do I report a bug?

Two ways:

• Create an issue at GitHub
• Contact me through the feedback button on the left.

Is my phone supported?

See the list of supported devices. Of course, it's quite likely the app would work on devices that are not included in this list as I am very short of testing equipment.

I can't see the book folder or the book file or I can't open the book

Most probably you're having trouble with security permissions.

I am seeing placeholders instead of images.

That may mean several things:

• the image wasn't found
• the image is in a format your phone can't read
• there hasn't been enough memory to load it or resize it

The app doesn't show the menu but instead asks me if I want quit.

You must have set the holding time too low. See the section about interaction.

How do I use dictionaries?

First you need to download some, then you have to install them and finally you need to know look up the word. You may do that by press, hold and release on a word, by press and release on the magnifying glass button or by selecting look up word from the main menu.

Features in detail

Here goes a detailed review of all currently implemented features.

Bitmap Font

Bitmap font rendering is achieved through my own implementation. The font used, Droid Serif, has been pre-rendered in several different sizes: 12px, 14px, 16px, 18px, 24px and 28px. All have been anti-aliased except for the 12px version, which looks much better without it. Supported (or sometimes partially) character ranges are:

1. Latin + Latin Supplement (191 chars)
2. Latin Extended A (128 chars)
3. Latin Extended B (14 chars)
4. Spacing Modifier Letters (11 chars)
5. Combining Diacritical Marks (6 chars)
6. Greek and Coptic (75 chars)
7. Cyrillic (255 chars)
8. Cyrillic Supplement (20 chars)
9. Latin Extended Additional (100 chars)
10. Greek Extended (1 char)
11. General Punctuation (34 chars)
12. Subscripts and Superscripts (1 char)
13. Currency Symbols (5 chars)
14. Letter-like Symbols (6 chars)
15. Number Forms (4 chars)
16. Mathematical Operators (12 chars)
17. Geometric Shapes (1 chars)

Hyphenation

Hyphenation for 29 languages:

1. Basque
2. Bulgarian
3. Catalan
4. Croatian
5. Czech
6. Danish
7. Dutch
8. German
9. Greek
10. English
11. Esperanto
12. Estonian
13. Finnish
14. French
15. Icelandic
16. Indonesian
17. Italian
18. Latin
19. Latvian
20. Polish
21. Portuguese
22. Romanian
23. Russian
24. Slovene
25. Spanish
26. Swedish
27. Turkish
28. Ukrainian
29. Welsh

Character Encodings

Support for 23 character encodings:

1. UTF-8
2. ASCII
3. ISO-8859-1
4. ISO-8859-2
5. ISO-8859-3
6. ISO-8859-4
7. ISO-8859-5
8. ISO-8859-7
9. ISO-8859-9
10. ISO-8859-10
11. ISO-8859-13
12. ISO-8859-14
13. ISO-8859-15
14. ISO-8859-16
15. WINDOWS-1250
16. WINDOWS-1251
17. WINDOWS-1252
18. WINDOWS-1253
19. WINDOWS-1254
20. WINDOWS-1257
21. KOI8-R
22. KOI8-RU
23. KOI8-U

Unit conversion

Conversion between 80 units in 11 unit groups.

1. Temperature
   1. C, K
   2. F, Degree of Frost
2. Length
   1. mm, cm, dm, m, km
   2. mil, in, ft, yd, fm, ch, fur, mi, land
   3. cable, nautical mile
3. Area
   1. mm2, cm2, dc2, m2, a, daa, ha, km2
   2. sq ft, sq yd, ac, sq mi
4. Volume
   1. mL, L, mm3, cm3, dm3, m3
   2. fl oz, gi, pt, qt, gal
5. Mass
   1. mg, g, kg, t
   2. gr, oz, lb, st, cwt, ton
6. Velocity
   1. m/s, km/h
   2. fps, mph
   3. kn
7. Pressure
   1. Pa, hPa, kPa, mbar, bar
   2. mmHg, inHg
   3. Atm
   4. psi
8. Power
   1. mW, W, kW, MW
   2. HPS
9. Energy
   1. Wh, kWh
   2. J
   3. cal
10. Linear density
    1. DPI
    2. DPCM
11. Angle
    1. rad
    2. deg

Images and styling

• Supports italic, bold and headings
• Supports text centering
• Supports images and alt text
• Supports horizontal rulers
• Partially supports pre text
• Doesn't support CSS
• Doesn't support tables
• Doesn't support links and anchors

Portable book settings: the .alx and .alb files

After opening a book for the first time, Albite READER will create a file with the same name, but with an .alx extension. This is a binary file containing your book reading progress. This includes:

• Current chapter and position
• Current hyphenation language
• Last visited position in every chapter
• Current encoding of every chapter

If you make any bookmarks in a book, Albite READER will also create a .alb file. This is a XML file which contains your bookmarked text and positions.

There are several advantages of this technique compared to the usual approach of using the RMS:

• You can backup your reading progress
• All your book settings are preserved upon application update
• You can continue reading on another phone
• Your bookmarks are completely accessible so you can open them in a text processor.

Used resources

All used sources and binaries are available at GitHub.

APIs

kXML2

It's a BSD-licensed XML pull parser, especially adequate for Java Mobile. It's small and unobtrusive. You can read more at their homepage.

AlbiteZIP

It's a Java Mobile port of GNU Classpath's java.util.zip package using the AlbiteRandomReadingFile API, which implements a RandomAccessFile with writing capabilities stripped away. Reading EPUB files relies on AlbiteZIP to work with their archives. AlbiteZIP's sources and some sample code are available at GitHub.

AlbiteCharacterDecoder

Provides the ability read characters not natively supported by Java's InputStreamReader. The API is based on some code from libiconv. Sources, examples, tests and binaries are available at GitHub.

AlbiteUnits

A simple java API for converting various physical units. Sources and binaries at GitHub.

ZLTextTeXHyphenator

Zlibrary's hyphenator used in FBReaderJ. Licensed under GPL 2.

Fonts

Droid Serif

That's the font used on Android devices. It's quite nice and is built with the idea of rendering well on small screens and at small sizes. It supports some good amount of glyphs (around 850) and character ranges. It's licensed under the Apache 2.0 license. You can download the Droid fonts in TTF from here.

Building fonts

In order to use the font in Albite READER you need to build it in the right format.

Firstly, install AngelCode Bitmap Font Generator. Now, you need to create a bitmap font using the app. We need a bitmap font with xml descriptor, so BFG will produce a png with a xml file. Take care to hold all the glyphs on a single page and make the page's area as small as possible.

Then, you need to manually edit the newly created xml file in a suitable form. This time you need to use AlbiteFontBuilder, which will produce the final files. See its page for more info.

Note that in order to implement italic text you need to have two fonts, i.e. two versions of the same font.

If the process is still unclear, you'd better explore the files of the font resources used in Albite READER.

You may download the sources and binaries of the bitmap fonts used in Albite READER at GitHub.

Hyphenation patterns

The used hyphenation patterns are the ones from TeX's site or some modified versions from FBReaderJ.

Building the patterns

For every language you need to have the patterns in a separate txt file. Each patterns should be on a separate line. Then run AlbiteTeXBuilder to build the file that will be used in Albite READER.

You may download the sources and binaries of the TeX patterns used in Albite READER at GitHub.

Dictionaries

There are some dictionaries ready for download!

• Merriam-Webster 1913, Abridged version (5.5 MB) based on OPTED. Abridged using the 3esl word list.
• Merriam-Webster 1913, Full version (13.6 MB) based on OPTED. Note that the index alone is 1.5MB large, so you need a device with loads of free memory and fast implementation of the File API.
• Some glossaries from Wiktionary. Include: Architecture Terminology, British Firefighters Jargon, Chess Terms, Irish Slang and Jargon, Library and Information Science, Military Slang, Nautical terms, Scottish Slang, South-African Slang, Truckspeak, US Navy Slang.

Note that the in order to be used in AlbiteREADER the dictionaries must be unzipped first. See here for installation instructions.

All sources and binaries may be found at GitHub.

Building your own dictionaries

Dictionaries are prepared as XML files that are then converted into binary files using AlbiteDictionaryBuilder. Dictionary entries can also be filtered against a wordlist so that one can automatically create abridged editions. See the page of the tool for some more exhausting information.

Graphics

Most graphics are made by me, except for the book icon that is made by SimioGraphics and the tiny icons of the folders, files, the check icon and the broken image icon that I downloaded from the internet.

Building the graphics

You need to use AlbiteImageBuilder to build the images into the binary format.

Current limitations

There are too many limited factors: your phone is limited, Java Mobile is limited and my personal time is limited. So, it points to the conclusion that Albite READER is limited, too. I'd like you to know of the current limitations, so that you can decide for yourself if they may stand in your way.

• No support for links and anchors (i.e. objects findable by their id)
• No support for toc.ncx. Chapters are made according to the files from the spine element in the opf file and are titled using a successive number.
• No support for accelerometers. I know it's cool, but there are some technical limitations to consider, including battery life when reading for a long time. No to mention that I often tilt the phone to a variety of angles if I am reading in my bed.
• No book library. Books are opened through a file browser.
• Images are shown in separate pages.
• Font is available in four sizes only. That's because bitmap fonts are being used. Using SVG/TTF fonts is not only slow (one can cache the glyphs after all), but ugly. Or one may need super-sampling which would make it terribly slow. Java Mobile on the other hand, has limited supported for fonts. It supports a maximum of three font sizes, and often limited amount of glyphs. Not to mention the fact that font rendering in Java Mobile is dreadfully on some devices (like my Samsung GT-5230).
• No support for subscript and superscript. That's because of the previous limitation.
• No support for tables.
• No support for CSS.
• Books with too many chapters might make the current TOC unusable. For instance, the complete War and Peace has more than 300 chapters, so the list of chapters becomes incredibly long and painful to browse.
• Languages with right-to-left text direction or hieroglyphic ones are not supported, including Chinese, Japanese, Hebrew, Arabic, etc.
• No language localization. In other words, the app is available only in English.
• No bold fonts. Instead of using bold fonts, the text is rendered in another color. Using bitmap fonts would significantly (i.e. at least twice) increase the size of both JAR and needed heap memory.
• There is a theoretical possibility of corruption of the .alx files. More precisely, it can happen if the battery dies exactly when saving the data to the phone or if the app is closed using the red key and it is unable to close fast enough. Thankfully enough, this possibility must be very slight in most situations.