This is the calfw user manual.

Copyright © 2011-2012 SAKURAI, Masashi

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

This document explains how to use the calfw calendar for emacs.

Introduction
************

Calfw is an extension to emacs to display a pretty calendar in the Emacs buffer. Currently, calfw has 4 views, month, 1 week, 2 week and day view.

Installing calfw
================

Calfw can be downloaded from https://github.com/kiwanami/emacs-calfw. Copy the lisp files to a directory in your emacs load path and add (require 'calfw) to your emacs init file.

howm
----

calfw can read howm calendars by including (require 'calfw-howm) in the init-file and ensure calfw-howm.el is in the load path. To open a howm calendar through calfw in emacs, type M-x cfw:open-howm-calendar.

Google calendar (ical)
----------------------

calfw can read howm calendars by including (require 'calfw-ical) in the init-file and ensure calfw-ical.el is in the load path. To open a howm calendar through calfw in emacs, type M-x cfw:open-ical-calendar.

Org-mode (org agenda)
---------------------

calfw can read org agendas as calendars by including (require 'calfw-org) in the init-file and ensure calfw-org.el is in the load path. To open an org agenda through calfw in emacs, type M-x cfw:open-org-calendar.

cal
---

calfw can read the default emacs diary by including (require 'calfw-cal) in the init-file and ensure calfw-cal.el is in the load path. To open a howm calendar in emacs, type M-x cfw:open-diary-calendar.

Basic Usage
===========

Once calfw is installed, you can run cfw:open-calendar-buffer to open a calfw buffer that fetches information from the emacs built-in calendar.

The default is a monthly display, but you can view a fortnightly display by pressing T, a weekly display by pressing W or a daily display by pressing D.

Move around to see the difference in highlighting by using f, b, n, p to navigate forwards and backwards per day or week respectively, or > < for next/previous month.

To view full entries for day with abbreviated listings, press SPC to display the pop-up buffer. Pressing SPC once again hides the buffer.

For a full list of key bindings, see List of Default Keybindings.

Contact the calfw developers
============================

The calfw home page is https://github.com/kiwanami/emacs-calfw.

You can reach SAKURAI, Masashi at m.sakurai at kiwanami.net.

Key Bindings
************

calfw is controlled entirely by keystrokes and commands, but also enables mouse interaction.

List of Default Keybindings
===========================

The following is a list of keybindings.

Navigation
----------

Left
b
h
     Previous day

Right
f
l
     Next day

Up
p
k
     Previous week

Down
n
j
     Next week

^
     Beginning of the week

$
     End of the week

Home
     First day of the month

End
     Last day of the month

M-v
PgUp
<
     Previous month

C-v
PgDn
>
     Next month

t
     Today

g
     Absolute date (YYYY/MM/DD)

TAB
     Next item in a day

Display
-------

M
     Display month

W
     Display week

T
     Display fortnight (14 days)

D
     Daily view

r
     Refresh data and redraw content

SPC
     Pop-up detail buffer

RET

[click]
     Jump (in howm and org-mode)

q
     Bury buffer

Binding Keys
============

Key binding like any other emacs application.

Modifiers
=========

Commands
********

If you've used emacs before you'll find commands and functions familiar. Commands are functions that can be bound to keys and executed interactively. A command expects a certain number of arguments and any that are not supplied will be prompted for.

Customise
*********

Holidays
========

Format of months and days
=========================

Faces
=====

Grid frame
==========

Line breaking
=============

Calfw framework details
***********************

This chapter describes in further detail the mechanisms of calfw.

Introduction
============

Schedule data which are shown in the calendar view, are collected by a list of the struct CFW:SOURCE objects through the named argument variables :CONTENTS-SOURCES and :ANNOTATION-SOURCES. The former source defines schedule contents. The later one does date annotations like the moon phases.

This program gets the holidays using the function calendar-holiday-list. See the document for the holidays.el and the Info text

Adding a new calendar source
============================

struct 'cfw:source' details
---------------------------

cfw:source-data details
-----------------------

Embedding calfw in other applications
=====================================

Calfw component
---------------

Buffer
------

Region
------

Text
----

Destination and View
--------------------

Calfw objects
=============

Overview
--------

cfw:component
-------------

cfw:model
---------

cfw:dest
--------

Application desgin
==================

Example Configurations
**********************

Howm example
============

     (eval-after-load "howm-menu" '(progn
       (require 'calfw-howm)
       (cfw:install-howm-schedules)
       (define-key howm-mode-map (kbd "M-C") 'cfw:open-howm-calendar)
     ))

If you are using Elscreen, here is useful.

     (define-key howm-mode-map (kbd "M-C") 'cfw:elscreen-open-howm-calendar)

You can display a calendar in your howm menu file

     %here%(cfw:howm-schedule-inline)

Org example
===========

     (require 'calfw-org)

Then, M-x cfw:open-org-calendar.

ical example
============

     (require 'calfw-ical)
     (cfw:open-ical-calendar "http://www.google.com/calendar/ical/.../basic.ics")

cal example
===========

     (require 'calfw-cal)

Then, M-x cfw:open-diary-calendar.

General Settings
================

The calfw view can display many schedule items, gathering some schedule sources. Using the function cfw:open-calendar-buffer is the general way to display the schedules.

     (require 'calfw-cal)
     (require 'calfw-ical)
     (require 'calfw-howm)
     (require 'calfw-org)

     (defun my-open-calendar ()
       (interactive)
       (cfw:open-calendar-buffer
        :contents-sources
        (list
         (cfw:org-create-source "Green")  ; orgmode source
         (cfw:howm-create-source "Blue")  ; howm source
         (cfw:cal-create-source "Orange") ; diary source
         (cfw:ical-create-source "Moon" "~/moon.ics" "Gray")  ; ICS source1
         (cfw:ical-create-source "gcal" "https://..../basic.ics" "IndianRed") ; google calendar ICS
        )))

The function cfw:open-calendar-buffer receives schedules sources via the named argument :CONTENTS-SOURCES.

One can customize the keymap on the calendar buffer with the named argument :CUSTOM-MAP of CFW:OPEN-CALENDAR-BUFFER.