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.3?

Version 2.3 adds some useful features and improves robustness of syncing events.

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 overwriten or ignored when syncing with Google Calendar
MULTIDAYTHRESHOLD
The event end time for a multiday event, in hours, after which it will be displayed on the last day. eg. 
MULTIDAYTHRESHOLD=8
Displays the last day of any event which finishes after 8am and hide those which end before that. This is useful to prevent overnight events from showing both days. For example a concert that starts at 10pm and finises at 12:30am the next morning.
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

Project
Load...  L
Load a new diary project. An ASL file requester will open, allowing you to choose the diary file to load. If the currently loaded diary has been modified and not saved, a warning requester asking if you want to proceed will open giving you the option to cancel the load.
Append...  A
Append a diary file to the current one. This will add the events in the newly chosen diary file to the first. No check for duplicates is performed. When saving the original file name will be used.
Save  S
Saves the currently loaded diary back to it's original file. If the diary has never been saved, ie. it's a completely new diary, then a file requester will open to allow you to choose a suitable file name.
Save As...
Save the current diary to a new file. When invoking this a file requester will open allowing you to choose the location to which you wish to save the file. By default an icon will be created for the project.
About... ?
Yes, amazingly, after more 10 years, the About menu option does something, we'll let you discover it's wonders for yourself!
Hide  H
Hide the GUI. Closes the diary window, but doesn't leave the icon on the Workbench. The GUI maybe reopened using the hot key combination, or via Exchange. Before closing, if the diary has been modified and not saved a warning requester will open, giving you the options to save, save as, not save or cancel the hide.
Iconify  I
Iconify the GUI,Closes the diary window, and leave an icon on the Workbench. The GUI maybe reopened by double clicking on the icon, using the hot key combination, or via Exchange. Before closing, if the diary has been modified and not saved a warning requester will open, giving you the options to save, save as, not save or cancel the iconification.
Quit  Q
Quit the diary program. Again a warning requester will open if the diary has been modified without saving.
Settings
Save Settings
The current settings will be saved to the current diary project icon as tool types. This includes all font and pen colour data as described above, and the current view mode. Any unrecognised tool types in the icon will be preserved.
Display Mode
This sub menu offers three options, Days In View (two days side by side), Week In View, (seven days with an eighth section display a calendar), Month In View (the whole calendar month displayed at once).
Edit Mode
Delete Mode
These two mode are mutually exclusive, in Edit Mode, you can double click days / events to crate /edit the details. In Delete Mode, double clicking an event will ask if you want to delete it from the diary.
Syncing
This menu is disabled unless the diary has been setup for syncing with a remote CalDAV server, such as Google Calendar.
Enable Syncing
Syncing the diary with the remote server can be temporarily suspended by deselected this menu checkmark item. When this item is unselected the periodic syncing of the diary will not occur, and any changes will not be sent to the server.
Sync Diary
Force an immediate sync of the diary, the appropriate syncing script will be called, and any changes in the remote server will be reflected in the diary afterwards.
Scripts
This menu is customisable, see the SCRIPT tool type mentioned above.
Execute Script...
Execute a script chosen via file requester. The execution routine will determine whether best to execute via ARexx or the shell.
Custom Scripts
Custom script entries follow on from here. The default installation provides the following.
Export AS ICAL  1
Exports the currently selected event as an iCal formatted VCALENDAR file.
Import From ICAL  2
Imports and event from a ical formatted VCALENDAR file.
Search Diary  3
Search the diary using AmigaDOS patterns.

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 four 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.

The third group consits of the syncing status gadget. If periodic syncing is enabled then the gadgets shows as green "earth" button, if disabled 'red', if syncing is taking place then the button image is replaced with an animated syncing image. Clicking on the is gadget will cause a sync operation the same as the "Sync Diary" menu above. Next to this is the alarms button, this will show as a bell icon when an alarm has been triggered. Clicking on the bell will open the new alarms window, with a list of triggered alarms.

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!
  5. 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.
  6. 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.
  5. Set the time offset the alarm triggers at, in days, hours and minutes.
  6. 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).
  7. Relative to end: if this is checked the alarm timing will be calculated relative to the end of the event, rather than the start.
  8. 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 exchange 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 exchange 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.
  • MODIFIED: Modifications made to this event
SET
KEY/N,UNIQUE/K,URL/K,SELECTED/S,DELETED/S,FIELD/K,STEM/K,VALUE/K
Modify 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
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
VALUE
The value of the field specified by FIELD, ignored if STEM is specified
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
  • MODIFIED: Modifications made to this event
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 at program exit.
     

     
KEY/N/A

     
The key of the event to delete

     
FORCE/S

     
Supress warning requester

     
REALDELETE

     
Requires FORCE: Don't transfer this event to the deleted list but really delete it, if it's already on the deleted list it will be truly deleted

    

   

   
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.
    • 
      
  • SYNCING: 1 if a sync process is taking place. The sync gadget will display a rotating animation
    • 
      
  • 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
    • 
	  
  • NOGOOGLEMODE: if TRUE (1) options incompatable with Google Calendar are 
	      enabled even when syncing with a google account 
    • 
     

    

   

   
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 system notification 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 changes 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

	 
NOCASE

	 
DELETED

	 
Search the deleted list

    

   

   
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: