Week in View

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!

What's new in version 2.2?

Version 2.2 is small update to 2.1, free for existing 2.1 licensees. Neverless it contains some useful updates and a few bugs fixes.

What'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.

NOGOOGLEMODE
Disable the Google Mode. Allows advanced users to set any setting even those that may be overwrite or ignored when syncing with Google Calendar
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

GUI 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

GUI 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

Days Events 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

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

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 be displayed in the main diary window.
  2. Status: The Status of the event, Confirmed, Unconfirmed 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

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.

Time Zone Support

CalDAV Support

The AOrganiser 2.x series supports syncing with remote calendar servers, such as Google Calendar, via the CalDAV protocol. This is implmented by some extensions to the internal data format to store the needed extra meta data, extensions to the ARexx interface plus a set of python modules and script that implement the CalDAV client.

As CalDAV uses the iCal calendaring data format for it's "internal" data structure we get import and export of .ics/.vcal files for "free".

In order to facilitate syncing of remote and local changes to the diary there are callbacks, which call scripts after certain actions.

  1. SyncScript: This script is called periodically, or on demand from from the Syncing->Sync Diary menu item.
  2. EditScript: This script is called when an event item is edited. In fact it is called when the 'OK' button is clicked in the Event Editor Window
  3. DeleteScript: This script is called ftare an event is deleted from the diary

These scripts are setup through the ARexx interface, in practice the setup wizard handles this for the user and only very advanced users need to worry about the fine details of this process.

The Google Setup Wizard

Google Wizard GUI Google Calendar requires the use of the OAuth2 API, and the Google Setup Wizard will take the user through the steps required to allow AOrganiser access to your google calendar data. Part of the steps require you to log into your google account via a web browser and after opting to allow AOrganiser access to your data copy an authentication string back into the Wizards GUI. Odyssey or (perhaps Timberwolf) is recomended for this, other browsers may not work well or at all.

There are two possible starting points:

  1. Syncing an existing AOrganiser diary:
    You have an existing, AOrganiser diary, and you wish to synchronise this with your Google Calendar account, and thus with you phone or other mobile device....
  2. Syncing a new AOrganiser diary:
    You wish to create a fresh local copy of your remote google calendar.

Congratulations, your diary is now synced! As you add and delete events from your AOrganiser diary the changes will be reflected on your android phone and vice verca.

Advanced Syncing Considerations

Alarms

Alarms are a bit complex when syncing as, in the standard specification, there is no unique identifier. This means that there is no way to work out which alarms was modified when syncing the event it's applies to. As such remote changes to an event will reset all alarms and readd them, which might occasionally produce suprising results.

In addition Google Calendar does not allow setting custom messages for it's alarms and sets "place holder" values in the SUMMARY and DESCRIPTION fields. The syncing script intercepts these and replaces them with empty values in the internal alarm structure, so that when displayed the default values are used, see Alarm Editor section above. Google also only supports DISPLAY and EMAIL types.

To prevent accidental loss of data due to the above, a special "Google Mode" switches in when syncing with Google Calendar, this disables various fields in the alarm editor etc, prevent entering of data that might get ignored or overwritten. It can be overruled by adavced users if they set he NOGOOGLEMODE tooltype in the project icon.

To get arround the above considerations, if you want a custom alarm on your AOrganiser, either top show a custom message or play a sound etc. Mark the alarm as local after you have customised it. It will then not be synced or overwritten.

Event Status

Google will accept statuses of TENTATIVE (Unconfirmed) and CONFIRMED (Confirmed) andset the remote event accordingly, however if you set the event to CANCELLED then Google promptly deletes the event from it's server. Your local copy will be preserved.

ARexx and Python Scripting Support

AOrganiser diary has an extensive arexx command set, allowing powerful scripts to be written. In addition it comes with a set of python modules that facilate advanced operations such as conversion from and to iCAL data formats.

Arexx Commands

HELP
COMMAND/K
Get some some help on the arexx commands available or the command specified. If no options are specified a list of available commands will be returned.
COMMAND/K
Return the template of the specified command
LOAD
APPEND/S,FORCE/S,FILE
Load a new diary project.
APPEND/S
Append the events in the loaded diary to the currently loaded diary
FORCE/S
Supress the warning requester if the currently diary has been modifued
FILE
The file name of the diary to be loaded. If omitted a file requester will open for the user to choose a file
SAVE
FILE/K
Save the current diary to it's file.
FILE/K
Specify a new file to save the diary too.
SAVEAS
FILE
Save the diary to a new file.
FILE
The file name of the diary to be loaded. If omitted a file requester will open for the user to choose a file
QUIT
FORCE/S
FORCE/S
Supress the warning requester if the current diary is modified.
ADD
AMIDATE/K/N,DATESTRING/K,TIME/K,TITLE/K,NOTE/K,REPEAT/K/N,
REPEATTYPE/K/N,REPEATTILL/K,AMIREPEATTILL/K/N,AMIENDDATE/K/N,ENDDATESTRING/K,ENDTIME/K,
ACTION/K,ACTIONARGS/K,ENDACTION/K,ENDACTIONARGS/K,UNIQUE/K,FORCEUPDATE/S,ETAG/K,
LOCATION/K,ORGANISERNAME/K,ORGANISERURL/K,URL/K,SEQUENCE/K/N,TIMEZONE/K,STATUS/K"

Create a new event and add it to the diary. The event key is returned in the RESULT variable. If the UNIQUE indentifier is specified and a previous event exists with that identifier the command will fail, unless the FORCEUPDATE options is included, which case it will up date the relavent fields in the existing event.

Dates and times for the event can be set in two ways, either by specifying the number of seconds since 1st Jan 1978 (the amiga epoch) or by passing a localised string in the form "DD Month Year". The same rules apply to interpreting this string as with the event editor window.

AMIDATE/K/N
The date and time that the event starts at, expressed as seconds since the Amiga epoch (1.1.1978). Overides other date time options.
DATESTRING/K
The date of the event expressed as a DateString, ie a localised date typically of the form DD MMM YYYY
TIME/K
The start time of the event expressed as string in the form hh:mm
TITLE/K
The title or summary of the event, a single line of text
NOTE/K
A more detailed decription of the event, plus any details that may not fit into other catagories, can be multiline, any newlines must be AmigaDOS escaped ie *N
REPEAT/K/N
Whether the event repeats. 0 means no repeat, 1 or higher sets the repeat frequency.
REPEATTYPE/K/N
The type of repeat expressed as a number
  1. Daily
  2. Weekly
  3. Monthly
  4. Yearly
  5. Same Day Each Month
REPEATTILL/K
Datestring indicating the time date the event should repeat till. Omitting means repeat forever
AMIREPEATTILL/K/N
Reapeat enddate expressed as seconds since the epoch
AMIENDDATE/K/N
The date / time the event ends expressed as seconds since the epoch
ENDDATESTRING/K
The edn date of the event as a date string
ENDTIME/K
The end time expressed as hh:mm
UNIQUE/K
A unique indentifier. This must be a string of characters that uniquely indentifies this event, if not provided such an ID is created by AOrganiser. If provided and an event with the same unique ID already exists then the add will fail unless FORCEUPDATE is set
FORCEUPDATE/S
If set then update the event with matching unique ID
ETAG/K
A string that defines this specific state of the event. Usually you will get this from a remote server, and it can be used to test for changes in the remote copy of the event.
LOCATION/K
A single line string defining the location of the event. Usually geographic, but not required to be so.
ORGANISERNAME/K
Name of the organiser of this event
ORGANISERURL/K
URL of the orgnaiser. (usually a mailto: URL)
URL/K
URL associated with the event. This is most usually the URL of the event on a CalDAV server
SEQUENCE/K/N
Sequence level of the event. Any time the date / time and certain other attributes are changed the sequence level is incremented
TIMEZONE/K
Time zone of the event in IANA format. Ie Europe/London , America/Chicago or Asia/Shanghai etc etc
STATUS/K
Status options are
  • TENTATIVE
  • CONFIRMED
  • CANCELLED
HIDE
FORCE/S
Hide the GUI, without iconifying, the window maybe reopened via the CX_POPKEY combination or via exchnage etc. Swet FORCE to prevent a warning requester when the diary has been modified.
ICONIFY
FORCE/S
Close the GUI, and place an icon on the Workbench, double clicking the icon will reopen the GUI window, as will the CX_POPKEY combination and exchnage etc. Again FORCE supresses the warning on iconifying a modified diary.
GET
KEY/N,UNIQUE/K,URL/K,SELECTED/S,DELETED/S,FIELD/K,STEM/K
GET information about a specific event. The event may be located in the diary via a range of options, but only one of them may be used at a time.
KEY/N
Choose event by it's "KEY" as returned by ADD or by NEXT etc.
UNIQUE/K
Choose event via it's Unique ID
URL/K
Choose event via it's URL
SELECTED/S
Choose the event currently slected ion the GUI
DELETED/S
Look for the event on the deleted list, only KEY,UNIQUE and URL may be used with this option
FIELD/K
The field you wish to query, the value will be placed in RESULT
STEM/K
A stem variable to hold al the available data on the event
Fields are as follows:
  • KEY: Current Key, this is only valid for this session
  • UNIQUE: Event unique identifier if set
  • DATESTAMP: Last time the event was modified in seconds in amiga system time
  • ETAG: The etag as described in ADD
  • URL: Event URL.
  • AMIDATE
  • DATESTRING
  • TIME
  • TITLE
  • NOTE
  • ORGANISERNAME
  • ORGANISERURL
  • LOCATION
  • SEQUENCE
  • REPEAT
  • REPEATTYPE
  • REPEATTILL
  • AMIREPEATTILL
  • AMIENDDATE
  • ENDDATESTRING
  • ENDTIME
  • TIMEZONE
  • STATUS
  • ALARMS: Number of alarms set.
EDITEVENT
KEY/N,UNIQUE/K,URL/K,SELECTED/S,REVIEW/S
Opens the Event Editor window for the chosen event.
KEY/N
Choose event by KEY
UNIQUE/K
Choose event by UniqueID
URL/K
Choose event bu URL
SELECTED/S
Choose currently selected event in GUI
REVIEW/S
Open window in review mode, in this case the "OK" and "CANCEL" buttons will be renamed "Accept" and "Discard", on pressing "Discard" the event will be deleted.
NEXT
KEY/N/A
Get the Key for the next event in the event list.
KEY/N/A
The key of the current event or 0 to get the first event in the list
PREV
KEY/N/A
Get the Key for the previous event in the event list.
KEY/N/A
The key of the current event or 0 to get the last event in the list
SELECTEVENT
KEY/N/A
Select the chosen event in the GUI.
KEY/N/A
Choose the event to select via it's key.
SHOW

   Display the GUI, unhide, uniconify or bring to front as required
   
DELETE
KEY/N/A,FORCE/S
Delete an event. When deleted events are put onot a seperate deleted list. Details can be accessed via this list, for processing with scripts that may need to handle sync related tasks etc. The list is finally flushed ecah time the diary is saved.
KEY/N/A
The key of the event to delete
FORCE/S
Supress warning requester
SHOWDATE
AMIDATE/K/N,DATESTRING/K,TODAY/S
Display the specified date in the GUI.
AMIDATE/K/N
Specify date in seconds sunce the epoch, ie Amiga system time
DATESTRING/K
Specify date as a human readable string, using localised names for months etc.
TODAY/S
use todays date as the date to show
SHOWEVENT
KEY/K/N,UNIQUE/K,URL/K,SELECTED/S
Display the specified event in the GUI
KEY/N
Choose event by KEY
UNIQUE/K
Choose event by UniqueID
URL/K
Choose event bu URL
SELECTED/S
Choose currently selected event in GUI
GETDIARYINFO
FIELD/K,STEM/K
Retrieve global information about the diary.
FIELD/K
Specify the individual field that you want to retrive the value is placed in RESULT
STEM/K
Specify a stem variable where available data can be placed.
The following fields are available:
  • FILENAME: The filename to the diary was loaded from and will be saved to by default
  • URL: The url of the remote CalDAV this diary is synced, if there is one
  • SERVERTYPE: the type of server, this is an informal string that scripts can use to distinguish between servers types, a typical value would be "GOOGLE"
  • CTAG: The "ctag" representing the current state of this diary
  • SYNCTOKEN: the sync-token representing the current state of this diary
  • ENTRIES: Number of entries in the diary
  • SYNCCOMMAND: The script to run when syncing is required
  • EDITCOMMAND: The script run after editing or adding an event
  • DELETECOMMAND: The script run after deleteing an event
  • CREDENTIALS: Custom string representing the credentials required to log in to the CalDAV server
  • SYNCENABLED: 1 if sync enabled 0 otherwise.
  • HEADERFONTNAME: Name of the font used for the event gadget headers
  • BODYFONTNAME: Name of the font used for the event gadget body
  • CALENDARFONTNAME: Name of the font used for the calendar gadgets
  • HEADERFONTSIZE: Size of the header font
  • BODYFONTSIZE: size of the body font
  • CALENDARFONTSIZE: Size of the calendar font
  • MODIFIED: 1 in the diary is modified 0 if not
  • TZID: the Diaries default TimeZone ID
  • DSTRULE: the diaries default daytime savings rule
  • TZSTANDARD: Standard timezone
  • TZDAYLIGHT: Daylight savings timezone
  • UTCOFFSET: the offset from UTC in minutes
SETDIARY
FIELD/K,STEM/K,VALUE
Set some or all of the diary's global values.
FIELD/K
The field you wish to set, when setting individual attributes,
STEM/K
A stem value to set multiple attributes, only those attributes added to teh stem will be set. See GETDIARYINFO for list of attributes
VALUE
The value of the attribute when setting via FIELD
ADDALARM
EVENTKEY/N/A,ALARMKEY/K/N,ABSOLUTE/S,RELEND/S,AMIDATE/K/N,ALARMTYPE/K,ACTIVE/S,INACTIVE/S,LOCAL/S,REMOTE/S,ATTR1/K,ATTR2/K,ATTR3/K
Add an alarm to a given event, or modify an existing one.
EVENTKEY/N/A
The key of the event to which you wish to add the alarm
ALARMKEY/K/N
The key of the alrm you wish to modify, if omitted creates a new alarm
ABSOLUTE/S
The alarm time is absolute and not relative to the event timeing
RELEND/S
The Alarm is relative to the end of the event rather than it's start time
AMIDATE/K/N
The number of seconds after which the alrm activates, negative values happen before the event, set to zero to conincide with the start of the event
ALARMTYPE/K
The type of alarm
  • DISPLAY: Displays a RingHIO message or a requester
  • AUDIO: Plays a sound.
  • EMAIL: Sends an email
  • PROCEDURE: Executes a command or action
ACTIVE/S
Make this command active
INACTIVE/S
Make this command inactive
LOCAL/S
mark this alarm as local, shouldn't be synced or overwritten by a sync script
REMOTE/S
Mark this alarm as remote, ie it will be synced and remote changes will overwrite when synced
ATTR1/K
First attribute of the alarm, this value depends on the alrm type.
  • DISPLAY: Defines the title of the notification
  • AUDIO: Defines the audio fle to be played
  • EMAIL: Title of the email to be sent (unsupported at present)
  • PROCEDURE: Command to be executed
ATTR2/K
Second attribute of the alarm, this value depends on the alrm type.
  • DISPLAY: Defines the description for the notification body
  • AUDIO: Volume
  • EMAIL: Enmal body (unsupported at present)
  • PROCEDURE: Arguments to command
ATTR3/K
Third attribute of the alarm, this value depends on the alrm type.
  • DISPLAY: Use requester in non zero
  • AUDIO:
  • EMAIL: Recipient (unsupported at present)
  • PROCEDURE: Run from ARexx if non zero
DELETEALARM
EVENTKEY/N/A,ALARMKEY/K/N
Delete a given alarm on an given event.
GETALARMINFO
EVENTKEY/N/A,DELETED/S,STEM/K
Get information about the alarms set on a given event, the alarm data is passed via a stem var. If the stem is not pscified the number of alrms is returned in RESULT
EVENTKEY/N/A
The key for the event to be queried
DELETED/S
Look fr eent on the deleted list
STEM/K
Name of stem var to put data into STEM.0 will contain the number of alarms. Then STEM.1.<field> STEM.2.<field> etc the data. The folowing fields are set;
  • KEY: The Alarm key
  • EVENTKEY: key of the owning event
  • ALARMTYPE: Type of alarm
  • ACTIVE: Aalrm is active
  • LOCAL: Alarm is local and should not be overwriten by a sync operation
  • ABSOLUTE: Alarm time is absolute not relative to the vents time
  • RELEND: Alarm timing is relative to the end of the event
  • AMIDATE: The alarm timing is seconds from the event or from the epoch if absolute
  • ATTR1:
  • ATTR2:
  • ATTR3:
  • TITLE:
  • DESCRIPTION
  • USEREQUESTER
  • RECIPIENT
  • ACTION
  • ACTIONARGS
GETTIMEZONEINFO
TIMEZONE/K,FIELD/K,STEM/K
Get information about a specific timezone.
TIMEZONE/K
The timezone to be queried expressed in IANA form ie Europe/London if no timezone is specified the diaries current time zone is used.
FIELD/K
The specific field to be queried, value is returned in RESULT
STEM/K
The stem var to place all the data in:
  • TIMEZONE:
  • TIMEZONESTD: Standard time timezone short name eg GMT, EST etc
  • TIMEZONEDST: Datlight saving s timezone name eg BST, EDT etc.
  • UTCOFFSET: UTCOffset in minutes
  • UTCOFFSETSTD: UTCoffset of standard time
  • UTCOFFSETDST: UTCOffset of daylight savings time
  • UTCOFFSETRFC: UTCOffset in RFC format 0000
  • DSTSTART: Start time for Daylight savings
  • DSTEND: End time for daylight savings
  • DSTSWITCH: Time till next daylight savings switchover
  • TIMEFLAG: True is DST
  • TZID: the timezone id in IANA Form
  • DSTRULE: the daylight savings rule
SETAPPLICATIONBUSY

   Set the busy pointer on the application.
   
UNSETAPPLICATIONBUSY

   Remove the busy pointer on the application.
   
LOCKGUI

   Locks the GUI, which means that chnages to the diary do not trigger an update in the gadgets.
   
UNLOCKGUI

   Unlock the GUI.
   
REFRESHGUI

   Force a GUI refresh, sometimes useful after the GUI has been locked for while as, unlocking does not by itself refresh.
   
GETUTCOFFSETTIMEZONE
AMIDATE/K/N,STANDARD/S,DAYLIGHT/S,TIMEZONE/K/A
Get the UTC offset for a given timezone, either at specific time, or the standard or daylight savings values.
AMIDATE/K/N
The time, in seconds since the epoch, local to the timezone, to find the UTCOfset for.
STANDARD/S
Find the offset for the standard time
DAYLIGHT/S
Find the offset for daylight savings time
TIMEZONE/K/A
Timezone to find the time for in IANA format
AMIGADATETOPARTS
AMIDATE/K/N/A,TIMEZONE/K
Convert a date expressed as seconds since the epoch into a date expressed as a comma seperated list of "parts". A String is returned in the following format:
    YYYY,MM,DD,HH,MM,SS,Weekday,YearDay,IsDST
   
Timezone argument is currently ignored.
PARTSTOAMIGADATE
PARTS/K,STEM/K,TIMEZONE/K
Convert a date expressed as list of parts as described above to a date/time expressed as seconds since the epoch. The AmiDate is returned in RESULT. You need only specify as many parts as required to define the date/time, for example to express only a date you may omit the Hours and minutes and seconds terms. Stem and timezone arguments are currently ignored.
FINDEVENTS
AMIDATE/K/N,AMIENDDATE/K/N,DATESTRING/K,ENDDATESTRING/K,TODAY/S,DISPLAYED/S,REPEATS/S,STEM/K,FILTERFIELD/K,FILTEREXPR/K,FILTEREXCLUDE/S,SORTBYTIME/S
Search the diary with a range of conditions.
AMIDATE/K/N
Specify the start time of the search in seconds since the epoch, if omitted events are serach from the earliest possible time onwards
AMIENDDATE/K/N
Search the diary up till this date, expressed in seconds since the epoch, if ommited keep searching to the very last event in the diary
DATESTRING/K
ENDDATESTRING/K
As above but express the dates as "DateStrings"
TODAY/S
Limit the serach to events occuring "Today"
DISPLAYED/S
Limit the serach to those events currently displayed
REPEATS/S
Inlcude repeats in the search
STEM/K
Stem to place the search results in
FILTERFIELD/K
Field to filter search result on:
  • TITLE
  • NOTE
  • ORGANISERNAME
  • ORGANISERURL
  • LOCATION
  • CLASS
FILTEREXPR/K
DOS Pattern to user as filter
FILTEREXCLUDE/S
Reject matches rather than accepting matches
SORTBYTIME
Sort result by time, otherwise they arrive in "list order" which is arbitrary
REQUESTDATE
AMIDATE/K/N,DATESTRING/K,RETURNDATESTRING/S
Open a Date Requester to allow the user to choose a date. You can specify the intial date and the format you want the date returned in.
AMIDATE/K/N
Specify date as seconds since the epoch
DATESTRING/K
Specufy the date asn a Date String
RETURNDATESTRING/S
If set return a date string, otherwise return the date in terms of seconds since the epoch
REQUESTTIMEZONE
TZID/K,SETDIARYTIMEZONE/S
Open a Timezone Requester to allow the user to choose a timezone. You can specify the intial timezone as an IANA format name eg "Europe/London".
TZID/K
Specify the initial time zone
SETDIARYTIMEZONE
The diary's timezone is automatically set when selecting from the requester
The TZID of the chosen Timezone is returned in the RESULT variable.
RC is set to 5 if the requester is cancelled by the user.

Python Modules

AOrganiser comes with an number of python modules, designed to interact with the diary via the ARexx interface. Whilst primarily designed for the CalDAV interface, they may be useful for those want to develope their own scripts. You may find these modules in the Scripts directory under the main CalDAV module.

Example Scripts

The following example scripts are provided: