Cheqlist

Welcome to Cheqlist documentation! Most users want to start with the User’s Guide.

Cheqlist User’s Guide

Installing

To install and use Cheqlist, you must first install Qt, Python (Python 3 recommended) and PyQt5.

Cheqlist fully supports Linux and should work on Windows and macOS, but some things might not work properly or natively.

Arch Linux users can use the cheqlist package from the AUR. Users of other Linux distributions need to install it themselves; PyQt5 packages should be available in OS repositories. macOS users can install python3 from Homebrew, pip for that Python manually and pyqt5 from pip (in a virtualenv, or with pip install --user) to satisfy all dependencies. Windows users can use installers provided by Python, Qt and PyQt5.

Main Window

Cheqlist opens with an empty task list, but a file may be provided on the command line. There are three menus (File, Edit, Help) and two toolbars that allow access to common commands.

Tasks can be added by pressing Ctrl+T on the keyboard or by clicking the Add button in the toolbar/in the menu. Tasks can be edited with Ctrl+E or double clicking. Tasks can be deleted by pressing Delete or clicking the Delete button in the toolbar/in the menu. Tasks also offer right-click menus with Add/Edit/Delete and formatting.

The entire list can be cleared with Ctrl+R or the Clear button. There is no confirmation, but it can be undone (Ctrl+Z).

Files (*.cheqlist) may be opened or saved, see File format for details of what input is taken and what is saved to files. Opening or saving a file links Cheqlist to that file (further Save operations won’t ask for a file name). Closing Cheqlist with unsaved changes will prompt to save them.

Mac users: Replace Ctrl with ⌘ Command and Alt with ⌥ Option.

Formatting

There are four formatting options available: bold (Ctrl+B), italic (Ctrl+I), underline (Ctrl+U), and strike out (Ctrl+Alt+S). Bold, italic, and underline have no meaning to the application (they are for decoration only). Strike out has no meaning unless Ignore struck out tasks is enabled from the Edit menu (saved in configuration between sessions).

Pressing Ctrl+Up and Ctrl+Down moves items up and down on the list.

Undo, Redo, Undo Window

All operations can be undone. Saving a file clears the undo list. To see all operations, you can use the Show undo window option from the Edit menu.

Pasting items

The Paste items… option in the edit menu (Ctrl+V when not editing a task) allows users to add tasks from the clipboard. It can also be used to add multiple tasks without having to press Ctrl+T after every task (i.e. Collection Mode/Bulk Add) Input is parsed the same way as files — check the File format section for details.

Bulk operations

There are three bulk operations in the Edit menu. Check All marks all tasks as done (sets completion to 100%). Check None marks all tasks as undone (sets completion to 0%). Invert Selection marks all done tasks as undone, and all undone tasks as done (completion = 100% - previous completion)

File format

Cheqlist uses a very liberal parser for files, loosely based on GitHub Flavored Markdown’s list syntax. The following rules apply:

  • If a line starts with asterisks or dashes followed by spaces, those are removed. (bulleted list syntax)
  • If a line starts with [ ] (after removing asterisks/dashes), those are removed and the task is marked as incomplete.
  • If a line starts with [x] or [X] or [*], those are removed and the task is marked as complete.
  • If text is wrapped in single asterisks or underscores (*italic*, _italic_), it is interprted as italic text.
  • If text is wrapped in double asterisks underscores (**bold**, __bold__), it is interprted as italic text.
  • If text is wrapped in <u> HTML tags (<u>underline</u>), it is interpreted as underlined text.
  • If text is wrapped in double tildes (~~strikeout~~), it is interpreted as struck out text.
  • A zero-width-non-joiner character (U+200C) on both sides of a line may be used to preserve raw asterisks, underscores, tildes or <u> tags at start/end of lines.
  • Text formatting options may be mixed, eg. <u>~~***all formattings***~~</u>
  • Cheqlist itself starts lines with dashes and [ ] or [x] in saved files.

The source distribution has some example files that show available formats, alongside a file generator (that often produces garbled output to test the parser).

Configuration

Configuration is stored in ~/.config/kwpolska/cheqlist/cheqlist.ini. The current configuration values are:

  • [directories]
    • lastdir — last directory used when opening files
    • homedir — home directory for lists (used only if open_from is set to homedir)
    • open_from — place to open from (lastdir or homedir)
  • [settings]
    • ignore_struck_out (true/false) — whether or not to ignore tasks that are struck out

Logs are stored in ~/.config/kwpolska/cheqlist/cheqlist.log.

Cheqlist. A simple Qt checklist.

Info:This is the README file for Cheqlist.
Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2015-2016, Chris Warrick.
Date:2016-11-20
Version:0.3.1

PURPOSE

This is a simple checklist application, written in PyQt5.

SCREENSHOT

Cheqlist

INSTALLATION

pip install cheqlist

Make sure you have PyQt5 installed. AUR package also available.

If you are on Linux, run:

sudo update-mime-database /usr/share/mime

FILE FORMAT

GitHub Flavored Markdown is the usual file format:

- [ ] unchecked
- [x] checked

However, the parser is quite liberal when it comes to reading files. It also supports Markdown-style formatting for **bold**, *italic*, <u>underline</u>, ~~strikeout~~.

READ MORE

See the Cheqlist User’s Guide for more details.

Appendix A. Contribution rules

Info:Those are the contribution rules for Cheqlist.
Copyright:© 2012-2016, Chris Warrick.
License:3-clause BSD

Do you want to contribute to this project? Great! I’d love to see some help, but you must comply with some rules.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Issue reporting

GitHub Issues are the recommended way to report an issue.

When pasting console sessions, you must paste them fully, prompt-to-prompt, to see all the messages and your input. Trim only stuff that you are 1000% sure that is not related to the project in question.

General preparations, rules and pull process

Prepare

A GitHub account is recommended. Patches by e-mail are accepted, but I’d prefer to work via GitHub.

Rules

  1. Commits must have short, informative and logical messages. Signoffs and long messages are recommended. “Fix #xxx” is required if an issue exists.
  2. The following fancy Unicode characters should be used when needed: — “ ” ‘ ’. … should not appear in console output, but may appear elsewhere.
  3. For Python code, use the PEP 8 coding style and PEP 257 documentation style. For other languages, K&R style applies. Braces are mandatory in all blocks (even one-line blocks). Braces are on the same lines as class names and function signatures. Use 4-space indents.

Request a Pull

Done? Go hit the Pull Request button over on GitHub! Your request should be accepted shortly (assuming there are no major errors).

Appendix B. License for Cheqlist

Info:This is the license for Cheqlist.
Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2015-2016, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2016-11-20
Version:0.3.1

Copyright © 2015-2016, Chris Warrick. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the author of this software nor the names of contributors to this software may be used to endorse or promote products derived from this software without specific prior written consent.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Appendix C. Changelog

Info:This is the changelog for Cheqlist.
Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2015-2016, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2016-11-20
Version:0.3.1

GitHub holds releases, too

More information can be found on GitHub in the releases section.

Version History

0.3.1
  • Add Move Up and Move Down commands (Ctrl+Up, Ctrl+Down)
0.3.0
  • More resilient, regex-based input parser
  • Full file support (remembers file names, save on quit if changes made etc.)
  • Undo/redo capability for all operations
  • Better performance of large lists (patterns, opening)
  • Ability to paste tasks/insert from text (Ctrl+V)
0.2.0
  • Display exceptions in message boxes
  • More formatting: underline and strikeout
  • Remove sample items
  • Split into two toolbars (Main and Edit)
  • Make it possible to ignore struck-out tasks
  • Add right-click menus
0.1.6
  • Fix updating last used directory
0.1.5
  • Fix task counting in logs (prevents crash on write)
0.1.4
  • Support opening files (requires MIME database update)
0.1.3
  • Remember last location used
  • Add config file support
  • Add logging
  • Select newly added items (Ctrl+B/Ctrl+I will work, but will also clear the text while editing)
0.1.2
  • Add menu bar
  • Add Quit action (Ctrl+Q)
  • Add Edit action (Ctrl+E)
  • Add actions to (un)check all and invert checks
0.1.1
  • .cheqlist extension
  • minor fixes
  • demo files
0.1.0
Initial release.

Indices and tables