sufone / qawl

📖 Quran Reader for Linux, Windows, macOS

Qawl v2

Current status: 80% parity with previous version (missing dark theme, icons on hover tooltips, mostly)

This project uses Github Projects to plan development — feel free to join in!

Feel free to email me if you are interested in contributing right now, before the foundation is done: [email protected] . Sorry if things are a bit messy, but I recommend checking this repo out a few weeks later!

Old version: https://github.com/mr-islam/qawl

Sorry this readme is bad, making it public quickly in case people want to contribute early ♥

Development

Preparation

1. Make sure you have node properly setup with a recent version (I use 14.x).
2. Install yarn
3. Also ensure you have node-gyp (this guide can help)
4. Clone this repo
5. Run yarn to install dependencies

(The repo uses an automatic postinstall script to patch the npm package electron-update-notification to use a promise .then() instead of callbacks. I haven't been able to test if I set this up correctly, but hopefully it's fine. You can check the installed package files manually, or just message me for help to ensure it's all good.)

Action 5. Run a local build with electron-dev, has hot-reload 6. Build a package with dist-[platform] choosing the relevant platform from the scripts available in the package.json

Many thanks to Albert Nye for his svelte electron template!

License

Copyright (C) 2020-2021 Naved Islam

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

qawl's Issues

Reach out to all those who starred the previous repo

They may not know development has shifted to here completely, and that future versions are here only

They may also want to star this new repo and keep up with new updates

• Draft short, polite email mentioning the above
• Go through list of old stargazers and send

Setting the icon on Linux

Closing #34, but this remains for a later date

Contributions most welcome!

Keyboard shortcuts

• Implement hotkeys for all user interactable events
• Update titles of elements to reflect these shortcuts

Built app improvements (system icon, package name, window title)

Decide on an i18n solution, trying out many options. Go for a simple API, that works natively with svelte

Page 444 not in greyscale

Don't know if this is an issue but page 444 (Yā Sīn) is in colour and the others are not!

Implement Github Actions Build

Solve #13 and #11 – just need to bother set it up and test it works. I had a bad experience with travis CI a few years back, and don't want to put time working on the build process when I need to work on feature parity with the old version also

Can use this https://github.com/samuelmeuli/action-electron-builder

Example https://github.com/samuelmeuli/mini-diary

Internal icons for toolbar

See Phopsphor: https://github.com/phosphor-icons/phosphor-home

Really like their style, and they have all the icons we need

Problem: No svelte package for easy integration (with tree-shaking)…

Failing builds and dev-server runs: `unexpected token u in JSON`

Was having a persistent problem that resulted in a blank white screen upon launching Qawl either from an installed build (tried v0.0.3 and v0.0.4), or a dev server using the latest code. Seem related to what was reported in #11. Got an error:

Unexpected token u in JSON at position 0

And the files/lines cited didn't have any issue. Tried deleting node_modules and re-installing, didn't work. Uninstalling Qawl and deleting it's install directory from %appdata% on windows did the trick, and now the installed build v0.0.4 works. and

I'll leave this issue open until a few months go by and this issue doesn't re-appear, or we are able to pinpoint what caused this.

My dev server still fails to load the app, but at least it's giving a different error I can debug. Sigh. This really must be what #11 was facing, when BiL reported a blank white screen after building a version cloning the code from master!

Remember and load last open page on startup

First step for #23

document all keyboard shortcuts, update link on website

Waiting till #23 is done

Release initial version

This is important, so users can install this new codebase ASAP, and be in line to receive updates

Customizable keyboard shortcuts

• settings interface
• internal svelte store to save and load preferences
• update keyboard shortcut definitions to load chosen key from settings

Translate strings in the app

[Feature Request] Show single page

I suggest adding an option for showing a single page per layout (it could be a switch/radio button)

Window title - reflect current surah

simple electron API implementation, app already tracks current surah in store

Unmount toolbar component when on settings screen

Theme System

Use Svelte Stores to load theme across the app

Make an easy JSON style format where users can easily create themes, and make a PR to include them in the next update

Support setting independent dark and light themes (switching mechanism between dark and light... is more complicated #18 .)

Setup all contributors

https://allcontributors.org/

System to choose dark theme

Automatic at set time by user? Follow system theme? Manual using a button / keyboard shortcut?

Many users / systems don't properly use system theme, so maybe we should avoid it

Working page navigation with select + number + range

All good!

Writing tests, or at least a testing procedure

I've been meaning to learn how to write tests… something I hope to do still

If someone could contribute tests it would be really helpful to speed up releases, and would be a great learning opportunity for me as well!

Welcome! Using Notion for now

Hi, welcome 👋🏽

Currently using Notion to track development and progress: [remove - notion sharing is being bad]

Feel free to check if what you want is there already, or let me know any thoughts.

The #1 Priority is to reach feature parity with the old version

Update electron for m1 chip support

Qawl is so light that even in emulation mode it should perform as usual without any issue, but this should be taken care of.

Electron builder would also need to support this, I think 🤔

Then need to setup #22 to make these

Linux version

Quickly: I love Linux and want to offer a version, don't have a copy installed now (but want to install Elementary OS 6 when it's out) or the time to do it. I would like to provide AppImage and snap files

If anyone is on Linux and wants this app, I would really love help building it for Linux! The readme of this repo has the instructions, and it should very little time for you (and maybe a bit to download the high quality Quran images)

Let me know and I can help you do it.

Tooltips in app

Improve code standard (Variable, function and component names)`

The whole app is pretty decent I think, with comments where beneficial

But the variable, function and component names - even if mostly clear - are not consistent, and won't be intuitive for someone new to the codebase.

In the future, I will be more careful about this from the get-go, God willing, but for now we must repair:

• Choose a naming standard for each
• Update existing code to match (change each using search/replace across the codebase, testing after each change just in case)
• Document this standard

More options for hyperlink providers

For both tafsir and recitation purposes

Recitation:

• Muqri

There's something by quranacademy

link to Quranwbw too

Drag scroll + hide scroll bars

Till then, must show scroll bars

fix `enter` key behaviour when typing page number directly

Fix patch-package to work 😢

Made a big mistake by not setting this up, will make a release ASAP to get this out

Open in {Quran App}

Related to #3, from which the provider can be selected. Can offer:

• Quran.com
• Corpus.quran.com
• altafsir.org
• tafsir.app

Github actions for build

Free for open source, and would make life simpler

There's a nice electron build github action package, but it might be better long term to handcraft the actions

Use SVG / SVG based custom mushaf images

See: https://github.com/batoulapps/quran-svg

Their processed PNGs are higher quality and smaller in size than the current ones here

And even better… use custom CSS for the original SVG pages along with a future theming system (#8)… but using SVGs instead of standard raster images brings other layout (ie. sizing) challenges

Fully customizable reading toolbar

Users can

• Re order elements
• Disable / Enable elements

Will also be nice and allow for multiple external hyperlink buttons (each configured to a different reference) :)

Zoom

Have sensible maximum and minimum

Fix "more" button on Linux (not opening in browser)

The function is running correctly and it shows in the console

Probably some issue with Electron window config

But it works fine in windows

Marketing: Record video, take screenshots, update website

To update on the site

Upgrade electron version to 10

Page reading history

Like implemented in old Qawl

Todo:

• Lastpage component + function
• Update old page change components to save to lastpage store

Transition to Github Issues totally

I initially started with my personal task system on Notion, as mentioned in #1, but that's a very poor choice for a (hopefully) community project.

• Bring over all internal tasks + notes
• Start using wiki
• Start using projects
• Label and rename issues to be good

Save settings / last read stores to localstorage and reload on start

Settings screen

• Navigation with routes
• Store to handle choices

Request: Mac Version

Salam
May Allah reward you for the great work
I'd like to request for a Mac version of the app when possible.
Thanks.

Fix CSP by adding policy

As mentioned by @mbnoimi in #13

The error talks about CSP which is relevant when there are pages loaded from the internet, and Qawl doesn't load any part of the app from the internet

Anyways, I'll add the relevant security policy things soon

Tooltip library

Strings are ready as in #35, just implement something like tippy

• Choose library
• integrate tippy (or lighter equivalent)
• customize appearance and speed
• add option in settings to hide tooltips, but on by default

That last todo is the reason behind using a library — to enable easy toggle of this

Auto-update

Going with a notification – it's disrespectful imo to auto download a release in the background, especially for a large app like Qawl

This way, I can quite easily have a message show up in the user's app on launch as well 🤩

Try swipe.js for the page view

https://swipe.js.org/

Can use left right buttons easily.

I imagine the implementation to be: A total of 3 pairs of pages: one in the middle that is currently on screen for the user, one on the left that is current +2 / +1, and another pair on the right that is current -1 / -2. These pairs are set dependent on the current page, and changing page by either dragging or "next/prev page" buttons can do a smooth scroll.

Potential issues:

• Jumping to a specific page (can just set the middle visible pair to instantly change to user selected page, or run a check if it's before or after current page, set the relevant left/right off-screen pair to be that requested page and then do a smooth scroll. This second way brings up way too many issues on how this can interact with other parts of the app…)
• Would this library even work in a zoomed in view? Where there is already left/right scrolling?

The issues seem large and annoying, so this is low priority. But it's worth experimenting with in some branch.

Use platform native icons and other build assets

Like #41

Low priority, relatively, but important for a good experience.

Just need to read a lot of documentation from https://electron.build, and convert/resize assets and put them in the right palce

Make the readme pretty

• Logo, screenshots, center align, etc.
• Note about the Sufone collective

Important to encourage community involvement