DateLook 2.3 - User Manual

(c) 2001 - 2011 by Rene Ewald under GNU GPL.

0. Content

1. Introduction

DateLook is a free electronic date book that features alarms, the ability to handle cyclic events, supports printing and is fully mouse-driven. It has an import/export-function (vCalendar V 1.0-format) and is able to synchronise its local database with a remote database in the net. The synchronisation can use FTP or any net file system. Therefore it is suitable for multi-user-operation. DateLook provides an unconventional graphical user interface. It is written in Java and requires a Java runtime environment 1.5.0 or later.

[top]

2. How to use

The Main-window is split into the upper part with a calendar and the lower part, the "events display", to show your events as coloured rectangles. When the mouse is over a rectangle, then the summary of this event appears. The "events display" has a variable number of rows used to group the events as you like (e.g. row 1: family; row 2: work ...) and to prevent overlapping.

Dragging with left-mouse-button or rotating the mouse-wheel shifts the visible space of time. Dragging with right-mouse-button in the calendar or rotating the mouse-wheel while holding the shift-key zooms the visible space of time. If you use the wheel, then the shift or zoom speed depends on where the mouse-pointer is: fast in the year-bar, medium in the month-bar or slow in the rest.

A click with the right-mouse-button on an empty place of the "events display" or pressing control-m opens a pop-up-menu with the options:

Event Manager, Goto, Print, Predef Colours, Row Manager, Extended View, Show Row Labels, Save GUI-settings, Help, Revert & Exit and Exit:

Remark that pressing the F1-key opens the Help-window from each other window. Furthermore many functions can be controlled by keyboard. For details see chapter 2.11.

Note for Mac OSX users: To emulate the right mouse button (unfortunately absent on Mac Computers) press the command-key additionally before pressing the only mouse button.

[top]

2.1 Create a new event

Press the left-mouse-button into the "events display" at the place where your event begins and in the row of your choice. Drag to right to the place where the event ends and release the mouse button. Automatically the Editor-window appears. If you like to create a whole-day-event (0 - 24:00 e.g. a birthday) press additionally the shift-key while dragging.

The Editor-window shows different entries:

A right-mouse-click increases; a left-mouse-click decreases the value of an entry. For fast changes the mouse-wheel can be used too. Alarm can be set On or Off. But there are three rules that must be observed: Alarm (if On) must be equal or earlier than Begin, Begin must be equal or earlier than End and for cyclic events it is not allowed to overlap itself. If one of these rules is violated you can't save the event but the wrong entry is highlighted red.

Remark that there is no plausibility check for entered Begin-, End- and Alarm-times and -dates. If you enter e.g. the 31st of February or 02.30 at the day when the day-light-saving-time is switched, then the date and time is silently corrected to the 3rd of March or to 03.30 o'clock.

DateLook handles cyclic events. For that you can choose in the Cycle-entry a multiplier (range 1 to 9) followed by:

daily, weekly, monthly or yearly.

With the help of the multiplier cycles of e.g. 2 weeks or 3 months can be chosen. A cyclic event occurs first like a non-cyclic event according to its Alarm-, Begin- and End-time, but later on periodically with the given cycle. Of course the number of occurrences (including the first) can be chosen. The range is from 2 to 999. For your information the day of the last occurrence is shown right of that number.

An alarm (if On) is given for each occurrence. Note that the Editor-window shows the Begin-, End- and Alarm-time always for the FIRST occurrence of this event. The EventManager-window shows cyclic events only once at its first occurrence.

The summary of the event can be entered in the text field using the keyboard.

If you want to store additional information attached to that event, press the Description-button. The Description Editor-window appears now. Here a longer description can be entered. As long as the Description Editor-window is open the Editor-window is locked. Changes in the description are saved only with the save-button in the Editor-window.

Pressing the save-button saves the new event and closes the Editor-window. Pressing the cancel-button discards the new event and closes the Editor-window.

You can individually choose the colour of an event by pressing the colour-button. If done the ColourChooser-window appears. As long as the ColourChooser-window is open the Editor-window is locked. The ColourChooser-window displays eight rows for eight different colours. Each row consists of a Label-entry, three colour-values for red-, green- and blue-part of the colour (RGB, range 0 to 255) and the select-button to choose that colour for the current event. In the first row the current colour of the event appears. This colour can be changed by mouse-click on the colour-values. Left click increases; right click decreases the colour-value. Mouse wheel works too. In the following seven rows there are predefined colours and labels. They can not be changed here.

[top]

2.2 Edit or Print an event

A right-mouse-click on an event's rectangle or summary in the Main-window opens the Editor-window for that event. Another possibility is to open the EventManager-window as described above. Here a right-mouse-click on an unhighlighted event's row opens the Editor-window for that event. A right-mouse-click on a highlighted event opens Editor-windows for all highlighted events. Coming from the EventManager-window in the Editor-window an additional go to-button appears to make this event quickly visible on the Main-window.

In the Editor-window you can modify all entries. Furthermore here a delete-button appears to delete this event completely. The cancel-button discards changes and closes the window.

Pressing the Description-button the Description Editor-window appears to edit the event's detailed description. Changes in the description are saved with the save-button in the Editor-window.

The Print-button opens a printer dialog to print this single event including its detailed description.

In Main-window events can easily changed by drag-and-drop. With left-mouse-button events can be shifted to another date or row. Begin-, End- and Alarm-time are shifted by the same value. If you want to shift the event exactly by one day or you want to change the row only without changing of time, then press the shift-key additionally while dragging. After drop the Editor-window appears automatically. To save the changes press the save-button or to cancel the changes press the cancel-button.

While dragging pressing the cntrl-key makes a copy of the event.

[top]

2.3 Delete and undelete events

Open the Editor-window for the event you want to delete. This can be done by a right-mouse-click on the event's rectangle or its summary in the Main-window. Then press the delete-button in the Editor-window.

If you want to delete more than one event at once, then open the EventManager-window, select all events, you want to delete, with the left-mouse-button and press the delete-button in the upper part of the EventManager-window. The button text changes to "sure?". If you are sure press the button again within the next three seconds. Otherwise the button text returns to "delete" and you must start again.

Note that the selection model is the same as for Windows(c). Use the cntrl-key to add/remove a single event to/from an existing selection; use the shift-key to select a whole area between an already selected event and the event you click on.

Remark that deleted events are still stored in DateLook's local database. But these events are not visible for the user. Storing of deleted events is needed for synchronisation (see chapter 2.9).

Pressing the undelete-button in the EventManager-window undeletes ALL events that were deleted since last purge (see chapter 2.10) of database. These events are now highlighted and (if disliked) can be easily deleted again by pressing the delete-button. All other not highlighted rows collapse to a small stripe.

[top]

2.4 Alarm

If the Alarm-time of an event is reached or DateLook detects events with pending alarms (at program-start), then for each of these events an Alarm-window is opened accompanied by a beep. If the Alarm-time of an imported or newly created event is in the past, then no alarm is given.

[top]

2.5 Predefined Colours

DateLook provides the possibility to predefine colours for specific topics of events such as "family" or "sports" or what ever you want. The advantage is that you have a better overview of the kind of events in the Main-window.

The PredefColourEditor-window can be opened from Main-window by a right-mouse-click into the "events display" and choosing the Predef Colours-option.

This PredefColourEditor-window displays seven rows for seven predefined colours. Each row consists of a Label-entry, three colour-values for red-, green- and blue-part of the colour (RGB, range 0 to 255) and the colour-field to show how the colour looks like. Labels can be modified by keypad. First click into the field you want to modify and then edit the label text. The colours can be changed by mouse-click on the colour-values. Left click increases; right click decreases the colour-value. Mouse wheel works too. The save-button saves the changes of the labels and colours and closes the window. The cancel-button closes the window too but without saving.

Remark that the events don't contain any information about colour labels. They only contain the colour. This means if you change a predefined colour later, then all already stored events with that "old" label colour don't change its colour. Imported events have the colour chosen by its creator independent of his or your predefined colours and labels.

[top]

2.6 Row Manager

To change the number of rows displayed in the Main-window and to attach a text label to each rows use the Row Manager-window. By using text labels for rows it is very easy to manage e.g. attendance and resource availability information.

The Row Manager-window can be opened from Main-window by a right-mouse-click into the "events display" and choosing the Row Manager-option.

The Row Manager-window displays the Visible rows- field on the most upper side. The number can be changed by a mouse-click on the digit. Left click increases; right click decreases the value. The mouse-wheel can be used too. The range is between 5 and 20 rows.

The Row Manager-window contains one text-field for each row to edit the label text. Independent of the current number of displayed rows here all labels from row 1 to row 20 can be edited.

The save-button saves the all modified row labels and the number of displayed rows (in the Main-window) and closes the Row Manager-window. The cancel-button closes the window too but without saving. Then all modifications are discarded.

Remark that if you create a new event in e.g. row number 7 and then the number of rows are decreased to a value lower than 7, then this event is displayed in the lowest row. But it remembers internally the original row number 7 until it is dragged to another place and saved again. For this reason it is not suitable to change the numbers of rows very often. Best is to determine the needed number of rows if you start using DateLook and then never change it.

While exporting events DateLook stores the row where an event is displayed (see chapter 2.8 too.). If such an event is imported it is displayed in exact that row, independent of the row's label. But if the row number is greater than the number of currently displayed rows, then it is shown in the lowest row. For that reason if you use DateLook in a multi-user environment all DateLook instances should use the same number of displayed rows. If DateLook imports an event from other programs then this event is put to the most upper row.

[top]

2.7 Search for events

First open the EventManager-window. Enter in the text field one or more search strings separated by blanks. A search string can consist of alphabetic characters, numbers and special signs except of quotation (") or, if you like, of nothing (to quickly select all rows). If a search string should include blanks it must be encapsulated by quotation ("). Pressing the search-button starts searching. Searching is done within the Date-, Time-, Class-, Cycle- and Summary-column of the table, not in the descriptions of the events. (Remember that cyclic events occur only once in the table.) As result all rows containing ALL of the search strings are highlighted and the table scrolls to the first hit. All other rows collapse to a small stripe. A left-mouse-click into the table re-opens all rows.

[top]

2.8 Export and Import events to/from file

DateLook can export selected (=highlighted) events to a file in "vCalendar V 1.0"-format or events can be imported from a file in "vCalendar V 1.0"-format. This is suitable if you use DateLook at different computers e.g. at home and in the office or if you want to exchange events with other programs that understand the "vCalendar V 1.0"-format.

To export events open the EventManager-window. Select the events you want to export to a file with the left-mouse-button as described in the chapter 2.3. Then press the export-button. A file chooser appears. Select a directory here, enter any desired file name (file extension .vcs is recommended) and press the export-button of the file chooser. That's all. Remark that an already existing file will be overwritten without any warning. You can use the "search"-function to select events to export.

To import events press the import-button in the EventManager-window. Select a valid file in "vCalendar V 1.0"-format with the help of the appearing file chooser and press here the import-button. After successful import the new events are highlighted in the EventManager-window. All other rows collapse to a small stripe. A left-mouse-click into the table re-opens all rows. If you dislike the imported events, you can easily delete them all by pressing the delete-button as long as they are highlighted.

The import feature follows the rule that each event with an unknown or without an Unique IDentifier (UID) is taken over into the own (local) database. Otherwise if there is an event with the same UID in the local database, then the LAST-MODIFIED-property is compared and the younger one is taken. If there is no LAST-MODIFIED-property in the event in file, then this event is not taken.

All events which are deleted remain in the local database, but marked as deleted. During import, events with same UID of a deleted event are not taken over into the local database, but only if the deletion took place later then the last modification of the event to be imported. Otherwise the remote event will be imported.

Remark that the exchange of events with other programs than DateLook can lead to the lost of some properties of an event. Because not all programs can handle all properties. Especially some programs don't support cyclic events. Please, turn the special attention towards the exchange of events between hosts in different time zones. E.g. an event starting at 08.00 will start at 07.00 after transfer from a host in Berlin to another one in London, because this is exact the same time if globally seen.

If DateLook imports events created on a computer using a different character set, then these events are displayed properly. But if such an event is modified and saved, then all characters only belonging to the current character set (used on own computer) and not belonging to origin character set are replaced by question marks.

[top]

2.9 Synchronisation

DateLook can synchronise its local database with a remote database. The remote database can be stored in a file on a FTP-server or any other mounted or local file system. This file is in "vCalendar V1.0"-format too. The synchronisation takes place in two steps. First step is the import of events from the remote database according to the same rules as described in chapter 2.8 but including deleted events. Whereas the LAST-MODIFIED-property of a deleted event is set to the time of deletion. Imported deleted events remain marked as deleted. This means if there is a deleted event in the remote database with same UID as another in local database and the deletion took place later then the last modification of the local one then the event will be deleted from local database.

The second step is to overwrite the remote database with the updated local database (including deleted events too). But while the second step only events of the Class "Public" are written to the remote database. This is suitable for multi-user-operation to protect your "private" events from propagation into the remote (common) database.

To perform a synchronisation open the EventManager-window and press the sync-button. Now the Synchroniser-window appears. Here you have the choice between an FTP-server or two file-servers 1 or 2. To change click on this text field. If you choose FTP-server and the FTP-server needs authentication, please enter your user name ("UID") and your password ("PW"). Otherwise leave both entries empty. Remark that the password is stored unencrypted in a settings-file. In the entry "H/P" the host name and the path of the remote database (e.g. "ftp.blabla.de/datelook/database.vcs" or "h:\blabla.de\datelook\database.vcs") is required. The file name of that database is free. If it doesn't exist, it will be created during synchronisation. Note that the chosen file (remote database) will be overwritten with the updated local database independent of its old content.

Press the sync-button in the Synchroniser-window to start the synchronisation. If finished the Synchroniser-window disappears and in the EventManager-window all updated and imported events are highlighted. The number of deleted events is displayed on the upper side. If an error occurred during synchronisation, then the Synchroniser-window remains and shows an error-message. To close the Synchroniser-window without synchronisation press the close-button.

Remark that simultaneous synchronisation of different DateLook-users in multi-user-operation can NOT lead to a lost of data (provided that FTP- or file-server works well). But it can occur, that not all local databases are really synchronised. Because there is a race condition between to "Synchronisers". For that reason it is recommended to synchronise the databases again if you recognise some unexpected delay.

2.10 Purge the database

DateLook stores deleted events in the local and remote database to prevent the (re)import of already deleted events from remote databases and to request the deletion of events in other instances of DateLook. But this fact leads to a continuously growing database while the number of "undeleted" events can remain constant. Therefore from time to time it is suitable to purge the database of already deleted events. To purge the database open the EventManager-window and press the purge-button. The button text changes to "sure?". If you are sure press the button again within the next three seconds. Otherwise the button text returns to "purge". Purge can be undone by exiting DateLook via "Revert & Exit" menu-item.

[top]

2.11 Keyboard control

The following table shows available shortcuts:

Window Shortcut Function
Main Control-m open menu
Control-v switch between Extended and Simple View
Control-g open Goto-Window
Control-e open Event Manager
Control-o open PredefColour Editor
Control-p open Print-Dialog
Control-q Exit
Control-l toggle the visibility of the row labels
Control-r open the Row Manager
left/right shift visible space of time in small steps
Control-left/right shift visible space of time exactly one window size
Shift-left/right changes the zoom state
Editor Control-s, Control-q save changes of the event and close window
Control-c discard changes and close window
Control-d open Description-Editor
Control-o open Colour Chooser
Control-p open Print-Dialog
Description Editor Control-q close window
Control-c copy selected text to clip board
Control-x cut selected text
Control-v paste from clipboard
Colour Chooser Control-q, Control-s use changed current colour and close window
Control-c discard changes in current colour and close window
PredefColour Editor Control-q, Control-s save changed predefined colours/labels and close window
Control-c discard changes and close window
Row Manager Control-q, Control-s save changed row labels and number of shown rows and close window
Control-c discard changes and close window
Event Manager Control-q, Control-c close window
Control-e open Export-Dialog
Control-i open Import-Dialog
Control-s open Synchronisation-Dialog
Sync-Dialog Control-q close dialog and remember content of entries
Control-c close dialog and discard changes in entries
Control-s start synchronisation
Goto Control-q, Control-c close window
Control-g goto chosen date
Help Control-c, Control-q close window
Alarm Control-c, Control-q close window
Control-e open Editor-Window
all F1 open Help-Window

[top]

2.12 Start DateLook from command line

You can start DateLook from command line:

java -jar [PATH/]datelook23.jar for Linux or
java -jar [DRIVE:][PATH\]datelook23.jar for Windows or
java -jar [PATH/]DateLook.app/Contents/Resources/Java/datelook23m.jar for MacOSX.

If you don't want to use the default local database file (described in chapter 3), then you can specify any other database file as an optional start parameter. If not exists this file will be created else it must be in "vCalendar V1.0"-format.

e.g. java -jar [PATH/]datelook23.jar -d [PATH/]other.vcs

In this case DateLook displays only events from this file and stores all modification to there. But don't try to start two or more instances of DateLook with one and the same database file. This will fail because of the first instance locks that database file by creating a lock file "*.vcs.locked" in the same directory. For that reason don't kill a running DateLook because then the used database will NOT be unlocked and then you must delete the lock file manually.

If you want to store the settings on another place, than the user's default directory, then you can use the -s option followed by the path of the .datelook-directory (e.g. "/home/rene/othersettings" exclusive ".datelook"). If there is no .datelook-directory at the specified place, then it will be created with the default settings.

e.g. java -jar [PATH/]datelook23.jar -s [PATH_OF_SETTINGS]

[top]

3. Files

Linux, Windows: DateLook itself comes as a single JAR-file datelook23.jar. "23" stands for the version number "2.3". This file can be copied to a place where ever you want. Best places are e.g. /usr/local/bin or C:/Programme/....

Mac OS X: The application and all needed files are located in the Folder DateLook.app (including the jar-file datelook23m.jar). This folder is part of the download-file datelook23.dmg.gz. If datelook23.dmg.gz is mounted you can copy this folder where ever you like. But the Application-folder is recommended. Remark that the Finder hides the extension ".app". You only see "DateLook".

For all OS: The setting files and the database are generated automatically and stored in the subdirectory .datelook of the user's default directory (if not modified by start parameters, see chapter 2.12). These files are:

[top]

4. License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 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 General Public License for more details. you should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

[top]

For more information or support see http://www.datelook.de/.

Have a lot of fun.