AOrganiser - Diary

An Advanced Feature Rich Calendar For AmigaOS

Overview

The diary combines a simple to browse interface modelled on a typical pocket diary, with a range of powerful features, including repeating events and alarms. A suite of python and ARexx scripts offer import and export of iCal / VCal formatted events and invitations as well as syncing to a remote server via CalDAV.

You can now sync your AmigaOS diary with your phone or other mobile device via Google Calendar!

Whats's new in version 2.1?

Since version 1.4, the last release of the 1.x series, the feature list has been expanded considerably, with more 300 hours spent bringing the total up to nearly 27,000 lines of code!

System Requirements

AOrganiser version 2.1 requires AmigaOS 4.1 Final Edition or later to run at optimal efficiency, it may work on older versions of the OS, but some functionality and, in particular, menus will be unavailable as it uses the new menuclass.

Here are the detailed requirements:

Installation

AOrganiser is provided as a stand alone package, the archive may be unpacked to the location of your choice. However you may find it useful to run the provided installation script which can install needed python modules and make a fix to a known issues with some systems, if found.

General Usage

Getting Started

Setting Up The Diary

By far the easiest way to use AOrganiser is to have it start from WBStartup when you boot up the system and load a specific diary.

To set this up from scratch proceed as follows:

Creating Your First Event

Now you are ready to add your first event to the diary.

In Depth

This section takes a more in depth look at the features and options available in AOrganiser.

Starting AOrganiser

AOrganiser may be started from the Workbench or from the shell. If started a second time it will unhide / uniconify the GUI and bring the window to front, but all other options will be ignored.

Command Line Arguments and Tool Types

The following options may be passed on the command line and also as tool types.

CX_POPUP/K,CX_POPKEY/K,CX_PRIORITY/K/N,MODE/K,ICONS/S,FILE:
    

CX_POPUP
Whether to start with the GUI open or iconified. The default is to start with the window open. Options are:
CX_POPUP=YES - start with the window open.
CX_POPUP=NO - start iconified.
     
CX_POPKEY
Define the hot key combination for uniconfying / unhiding the GUI. Default is:
CX_POPKEY="CTRL ALT D"
     
CX_PRIORITY
Set the commodity priority, defaults to 0, there generally no reason to set this to anything else.
MODE
What display mode to start in. That is whether to display a "2 days in view", "week in view" or "month in view" style main window. The default is week in view. Options are:
MODE=DAYS
MODE=WEEK
MODE=MONTH
     
ICONS
Whether to create icons when saving the diary to a new file. the default is not save icons when start from shell but defaults to saving icons when started from Workbench. There is an addition tool type NOICONS that may be used to disable icon saving when started from workbench.
FILE
The name of the diary project file to load. When used as a tool type this overrides the path associated with the icon. However the current directory will still be defined by the parent directory of icon when starting from Workbench so the path defined by the FILE tool type must be absolute of relative to the icons directory. Generally the usage of the FILE tool type is discouraged and it is included for backwards compatibility, for those using old style WBStartup directories, where they might only want to copy the icon to WBStartup and not the diary project file itself.

The following options are passed as tool types only.

SCRIPT
The SCRIPT tool type is only read from the main program icon, and can used multiple times. It defines the user cutomisable entries in the script menu.
The format is:
SCRIPT=<menu label>,<script>
     
The menu label is the text you want to see in the menu, since menus are created by menuclass the menu shortcut can be defined by a leading character before a pipe symbol ("|").

The script argument should be the full path to the script that you want to execute, it may be a path relative to the program directory. By default the script will be launched via ARexx, if you want the script launched via the AmigaDOS shell then add a leading "@". This will be stripped before passing to the shell.

This following example sets up a menu entry "Search Diary" with a shortcut of RAmiga-1 that launches the search GUI script via the shell.
SCRIPT=1|Search Diary,@/Scripts/SearchGUI.py
     
GUI Pen Colours
The GUI pen colours can be defined by a set of tool types in the project icon. Colours are passed as ARGB hex values, the A (alpha) part is currently ignored and should be set to FF. The following are available:
FGPEN
The foreground pen, the default colour used for most GUI text.
BGPEN
The background colour for the main part of the diary interface, think of it as the colour of the "paper".
SELECTFGPEN
The colour of text on the title the currently selected day, or the corresponding highlighted day in the calendar gadget.
SELECTBGPEN
The colour of the background of the title of the selected day.
TODAYPEN
The colour of the text on the title of day gadget that represents the current date.
GREYPEN
A colour that is used for days in the preceding or following month in the month in view mode, and other places where the text has reduced emphasis, it's typically a light shade of the foreground colour.
DAYFGPEN
The colour of the text of in the calendar gadgets header (day names ).
DAYBGPEN
The colour of the background of the calendar gadget header.
Fonts
The fonts used by the event display gadget, and the calendar gadget can be customised. Font names must include the .font extension and the full path, there is no need quote font names with spaces. (e.g. FONTS:Monotype Corsiva.font)
Both the font name, and font size must be specified
All fonts default to the current window font, except the event body font which defaults to the window RastPort font reduced in size by 2 pixels.

This list of options is as follows:
CALENDARFONT
Sets the font for the calendar gadgets in the main window "days in view" and "week in view" display.
CALENDARFONT=FONTS:Monotype Corsiva.font
       
CALENDARFONTSIZE
Set the size of the CalendarFont set above.
CALENDARFONTSIZE=20
       
HEADERFONT
Set the font for the event titles, as displayed in the main diary window.
HEADERFONTSIZE
Set the size for the above font
BODYFONT
Set the font for the body text of the event, as displayed in the main diary window, this can be anything you prefer, but by default is a font 2 pixels smaller than the title font.
BODYFONTSIZE
Set the size of the above font

Menus

The Main Window

The design of the main diary window has been created to mimic a "real pocket diary" but without such slavish adherence to that idea, that it limits the functionality.

There are three viewing modes, Days In View, Week In View and Month In View.

All three views have a common header and footer.

Header


The header is comprised of three sections. The left two gadgets, toggle between Edit Mode and Delete Mode and are the exact equivalent of the menu items mentioned above.

The second group of 3 switch between Days in View, Week In View, and Month In View modes, and again correspond to the menus items in the Settings menu.

Finally the area on the right displays the current Date and Time, this automatically advances every internal 'tic' (which by default is 2 seconds). If you click on this gadget you are automatically taken to "Today" in the diary view.

Footer


The footer is comprised of three gadgets.

The central gadget shows the currently displayed month. Clicking on this gadget brings up a "Date Requester" that enables you to navigate to any date you choose (within the range of the AmigaOS epoch! 1978 - 2113).

On either side are two arrow gadgets, click on these to advance and go back by one page. That is by 2 days in days view, 1 week in week view and 1 month in month view. Press SHIFT and click to advance by 1 week, 1 month (actually 4 weeks) and 1 year, respectively. In any view mode, press ALT whilst clicking moves the date by just 1 day in either direction.

Day and Event Gadgets

The Main part of the window between the header and footer consists of 2 7 or 42 day gadgets depending on the mode. Their basic behaviour is the same in any mode, except that in the Month In View mode the day names are displayed separately at the top of each column and only the date number in the day gadget.

Each day gadget has a header section which displays the day and date. The current day, ie. "Today" will displayed with red header text, otherwise the standard background and foreground text colours are used. A single click on the header will select that day, it's selected status is indicated by a change of text and back ground colour, by default the text turns 'blue' and the back ground a 'darker yellow'. These colours can be customised, see above. When selected the corresponding date can be access via the ARExx functions with keyword 'DISPLAYED'.

Beneath the day header is a list of events, the maximum number displayable depends on whether in day, week or month mode. If there are more events in a day than can be displayed, a small exclamation mark will flag this at the bottom of the gadget area. Events are sorted into local time order. Events can be selected by single clicking on them, in which case they become the 'active' event, and can be accessed from scripts with the 'SELECTED' keyword. By default the event will display with the title in bold text and the location is a smaller font.

In Edit Mode double clicking on a day gadget header opens the Event Editor window, to create a new event on that day. Double clicking on an existing event will open the editor window with the details of that event displayed for editing.

In Delete Mode, double clicking on a day gadget does nothing (except select the day) and double clicking on an event will bring up a requester asking if you want to delete that event.

Calendar Gadget

In the days and week modes, a calendat gadget appears below the day gadgets, and in the eighth day slot, respectively. The days of the whole month currently displayed are shown here, and you can click on any one to jump straight to that day in the main window. The currently selected day is highlighted in the same colours as in the main part of the window, and "Today" is again highlighted in red. The names of the days are displayed in abreviated form across the top of the gadget. This gadget is also used in the "Date Requester".

Window Popup Gadget

The main window supports the standard reaction popup gadget, which allows you to snapshot this window, and iconify / quit from the respective menu options.

Keyboard Navigation

As well as the mouse based operation described above, AOrganiser also allows you to navigate via the keyboard.

In addition to the menu short cut keys noted above the left and right arrow keys can be used to "turn the pages" of the diary. Pressing the left and right arrow keys acts exactly the same as if you had clicked on the left and right arrow buttons in the GUI. The SHIFT and ALT qualifiers also behave the same. When you have arrived at you chosen day pressing the RETURN or ENTER keys will bring up the Event Editor to create a new event.

It's not currently possible to select events for editing via the keyboard, this may be added in a future revision.

The Event Editor

The event editor window is divided into 4 main sections.

Event Details

This is where you enter the general details of your event. The following fields are available.

  1. Title: The title of the event, a single line sumarey that will bedisplayed in the main diary window.
  2. Status: The Status of the event, Confirmed, Unnonfirmed or Cancelled
  3. Note: You can enter any details you like here, there is no limit to the size, though notes of more than 32768 chracters in length might show issues when processed by an ARexx script!
  4. Organiser: If you are not syncing the diary to a CalDAV server you may use this how you like, by default the first filed is the name, the second the url (usually a mailto: URL) if you are you should allow the sync / import scripts to set these fields as servers (particularly Google at any rate) can be fussy about their contents.
  5. Location: The location of the event. A real world address, telephone number or whatever...

Event Timing

When the event is to occur, events must always have a start date and time, but the end date and time are optional. When entered the end dat and time must always be later than the start date and time, this will be corrected if invalid data is entered.

Tip the fastest way to set the end date to the start date is to TAB through the date and time gadgets, once the TAB button is pressed in the End Date gadget the end date and time will be calculated to match the start (or later).

  1. The events timezone: The details of the events timezone, are displayed here, Country Name, Short Time Zone name, (UTC offset), Timezone Name, IANA TimeZone ID ion the form Europe/London. If no timezone has been set for the vwent this will be left blank, the event is then assumed to be in the local timezone that of the diary.
  2. Choose TimeZone Popup. This will popup a window to allow you to choose the timezone from a TimeZone requester window.
  3. Start and End Date: The start and end date may be entered here in text, the gadget will do a fairly good job of interpreting a range of formats. The follow are understood. (month names an abreviations are localised). An empty string in the end date will clear the end date, and empty string in the start date reverts to the previously entered date.
  4. Choose Date popup: The two buttons following the date gadgets bring up Date Requester windows to allow choosing the date via the a simple GUI as an alternate to typingin the date by hand, once you are used to typing in the date it's actually faster, but choice of entry method is always good :-).
  5. Event Time: Enter the events time of day in this gadget. You may either simply type the digits of the 24 hours time, or use the up and down arrow keys to adjust the hours and minuts, pressing TAB moves between the hours and the minutes, press TAB or ENTER once more to commit to the time change.

Event Repeats

Optionaly you can have an event repeat, events can repeat forever or stop repeating after a certain amout of time. Repeating events will be shown in the main diary window on each date they occur on, but individual repeat instances can not be edited seperately.

  1. Repeat type: A chooser gadget offering the available repeat options.
  2. Repeat Frequency: How often the repeat occurs, if set to 1 (default) a weekly event occurs every week, if set to 2 every two weeks etc etc.
  3. Repeat End Date: Sets the date after which no more repeats occur.
Alarms

The final section displays any alarms set on the vent, and allows adding editing or deleting alarms.

  1. Add Alarm: Adds a new alarm, opens the Alarm editor window to set the details
  2. Edit Alarm: Edit the alarm currently slected in "R" the alarms list.
  3. Delete Alarm: Delete the currently selected alarm
  4. Alarms List: A list of the alrms set is displayed, with a brief summary of their type and settings

The Alarm Editor

The alarm editor window, typically launched from the "Add Alarm" and "Edit Alarm" buttons in the Event Editor window, allows you to create or edit Alarms, which can be triggered at given time offset from the start or end of an event.

There are 4 types of alarms,

  1. Set the Alarm type
  2. LocalAlarm: If this is set the alarm is considred local to the current machine and should not be synced with or deleted by remote server.
  3. Set the time offset the alarm triggers at, in days, hours and minutes.
  4. After Event: If this is set the alarm triggers after the event, other wise it will trigger before the event (default is to trigger before the event).
  5. Relative to end: if this is checked the alarm timing will be calculated relative to the end of the event, rather than the start.
  6. Alarm details: The fields in this section vary depending on the alarm type.