Cleo documentation

Author: Terry Brown
Date: 20060914
Updated:20080328
Cleo version:0.18-0.25+

Contents

Introduction

cleo is a Leo plugin which adds arbitrary colouring of nodes, to-do priority markers, and time-required / progress display. Leo is a python based cross-platform outliner / literate programing tool / general data management environment.

cleo.py was originally written by Mark Ng, since then EKD and others have worked on it, most recently me, Terry Brown. I tidied up some internal parts and added some features, but here I'll just document the whole thing as it now stands, currently version 0.25 on 20080328.

Screenshots

(next section)

Current cleo (0.25)

Current cleo (0.25)

cleoicons.png

Older versions

Older versions

Note that some of these have too much going on, they're for illustration, not what you'd use generally.

prog.png

Unscaled progress bars, priority arrows and checkmarks, arbitrary fore and background colours.

scaleprog.png

Scaled progress bars.

showtime.png

Time and progress display, automatically updated because of '@project time' keywords.

Requirements

Short answer: cleo runs in Leo using Leo's Tk GUI and the Python Imaging Library (PIL) including the ImageTk module.

Cleo currently relies on the Tk Leo interface. It used to use Tk for drawing priority indicators, but now uses Leo's icon drawing code. I intend to migrate the progress indicators from the current red/green lines to icons similar to those used here (but better than those ;-). When the progress indicators have migrated to Leo icons cleo's only dependency on Tk will be the menus. If Leo offers a GUI agnostic menu API cleo will switch to that.

Settings

Leo supports @settings sections in documents. @settings used by cleo are:

@settings
    @color cleo_color_prog_green = 'blue'  # colour used instead of green in progress bars
    @color cleo_color_prog_red = 'orange'  # colour used instead of red in progress bars
    @data cleo_color_file_node_list
       # list of @file node types to color, e.g.
       @file
       @thin
       @auto

    @int cleo_prog_width = 18  # base width of progress bars
    @float cleo_time_init = 1.0  # default number of time units
    @int cleo_prog_scale = 1  # 0: no progress bars, 1: unscaled progress bars, 2: scaled progress bars
    @float cleo_prog_extra = 4  # pixels per time unit to add to width of scaled progress bars
    @string cleo_time_name = 'days'  # name of time unit (e.g. days, weeks, hours)

Cleo used to use these, but now just uses icon images for priority markers:

@color cleo_color_pri_1 = 'red'  # colour of priority level 1 marker
@color cleo_color_pri_2 = 'orange'  # colour of priority level 2 marker
@color cleo_color_pri_3 = 'yellow'  # colour of priority level 3 marker
@color cleo_color_pri_4 = 'green'  # colour of priority level 4 marker
@color cleo_color_pri_5 = 'blue'  # colour of priority level 5 marker

Icons

Cleo version 0.25 and later use Leo's icon functions, rather than using Tk to draw markers directly on the canvas. These icons are generated from an SVG file, that file and the icons themselves live in the leo/Icons/cleo directory of the Leo distribution, and you can replace the PNG images with any others you wish.

Usage

Cleo is enabled like like any other plugin, by editing the @enabled-plugins node in myLeoSettings.leo.

All functionality is reached via a right-click on a node's status icon area. This can create conflicts with other plugins that use a similar right-click.

Other features

@project nodes

@project nodes can be used to make updates of progress bars and displayed times automatic.

Whenever you change the progress-level or time-required on a node, cleo will search back up through the tree to find the highest level parent node with '@project' in the headline. cleo will then execute Re-calc. time required on that node. If the node contains '@project time' (one space) the Show times will also be executed on that node.

Remember that when a @project node is present, attempts to remove progress and time required values may appear to fail as Re-calc. time required replaces them as you remove them.

Re-loading colours

Remember that custom colours created with New colour aren't saved in the colour lists between sessions, but they can be reloaded from nodes by right clicking, see New colour for details.