AOrganiser - Diary
An Advanced Feature Rich Calendar For AmigaOS
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
You can now sync your AmigaOS diary with your phone or other mobile device via
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!
- The Event window features and extended range of options for entering information, the single line title and notes section have been expanded to,
- Multiline Notes
- and Location
- Alarms can now be set to trigger at arbitrary offsets from the start or end of the event, notifying via RingHIO, requester, sound or executing a command.
- Custom gadget to display the events in the main diary window, with cutomisable colours and fonts.
- Optimisations to the time entry gadget.
- Extended features in the built in calendar gadget, with a new choose date requester utilising the same gadget as you see in the main window.
- Fully customisable pen colours, allowing a diary look that suits your own preferences.
- Keyboard navigation in the diary window using arrow keys.
- The ability to select days or events and operate on them via arexx scripts.
- Massively extended ARexx interface.
- Extended but fully backwards compatible IFF diary file format.
- Extensive time zone support for event that take place in different parts of the country (or world) to the diary's primary locale.
- ICal and vCal import / export options.
- The ability to sync with Google Calendar via the CalDAV API.
- Advanced searching using AmigaDOS patterns.
- Much much more...
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:
- AmigaOS 4.1 Final Edition.
- ProAction Version 1.7 (1.9 recommended) provides GUI for various support scripts - more info
- Python (provided with AmigaOS) plus the following 3rd party modules:
- Python SSL is used to communicate with remote servers via the SSL security layers - Download from OS4 Depot
- AmigaVars is used to allow scripts to save and load settings as environment variables - Download from OS4 Depot
- Oauth2client, httplib2 and simplejson are provided with the AOrganiser package.
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.
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:
- Navigate to the volume where you installed AOrganiser and open the AOrganiser drawer on the workbench.
- Start the diary by double clicking on the diary program icon, diary will start with an empty diary, named "Unnamed"
- Save the diary, by choosing the menu item Project->Save, a file requester will open inviting you to choose a file to save too.
- Once you have chosen your preferred file name (mine is simply called "Andy") click OK in the file requester, the new "blank" diary project will be created, along with an icon.
- Now open the Workbench Prefs drawer and start the WBStartup prefs program
- Click on the Add... button on the right of the WBStartup window and, using the file requester, navigate to your saved diary file and add it to the list.
- Click the Save button at the bottom of the WBStartup to save your updated WBStartup prefs and close the program.
- Next time you reboot diary will start and load your new diary file, by default it will open it's window. If you would prefer it to start iconified, then add the tool type CX_POPUP=NO to the new diary projects icon.
Creating Your First Event
Now you are ready to add your first event to the diary.
- By default the diary starts in the week in view mode, you may browse through the weeks by licking on the left or right arrow button at the bottom of the diary window or choose a particular date by clicking on a date in the calendar gadget in the bottom right section.
- Browse to the date at which you would like to setup an event.
- Double click on the day name of the day you would like to create an event.
- A window with event details will open. The two most important fields are "Title" and "Location" as these will display in the main diary window after you save the event.
- The default title will be "New Event". Change this to something more suitable. remember to press RETURN or TAB to confirm you change as is standard in AmigaOS GUIs, then enter allocation in the Location gadget.
- The start date will be set will be set to the date of the day you double clicked on, the time by default will 09:00. You may adjust the time by clicking on the time gadget, then either typing in the new time (just type the digits) or by using the UP / DOWN arrow keys to adjust the hours and minutes.
- Once you are happy with the time you can save the event by clicking on the OK button.
- The event will now display in the main diary window, with the title in bold, and the location in smaller text beneath it, if the title or location were very long they will simply be cropped in the display, you can see more by making the diary window wider. If you hover the mouse over the event you will see a tool tip pop up with the events full title and location details.
- If you are happy with the changes you should now save the diary from the main menu, as you are working with a saved previously saved diary, Project->Save now saves to the project file without further request, if you want to save to another file for some reason, choose Project->SaveAs...
This section takes a more in depth look at the features and options available in 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.
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.
Define the hot key combination for uniconfying / unhiding the GUI. Default is:
CX_POPKEY="CTRL ALT D"
Set the commodity priority, defaults to 0, there generally no reason to set this to anything else.
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.
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.
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.
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:
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.
- 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:
The foreground pen, the default colour used for most GUI text.
The background colour for the main part of the diary interface, think of it as the colour of the "paper".
The colour of text on the title the currently selected day, or the corresponding highlighted day in the calendar gadget.
The colour of the background of the title of the selected day.
The colour of the text on the title of day gadget that represents the current date.
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.
The colour of the text of in the calendar gadgets header (day names ).
The colour of the background of the calendar gadget header.
- 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:
- Sets the font for the calendar gadgets in the main window "days in view" and "week in view" display.
Set the size of the CalendarFont set above.
- Set the font for the event titles, as displayed in the main diary window.
- Set the size for the above font
- 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.
- Set the size of the above font
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
There are three viewing modes, Days In View, Week In View and Month In View.
All three views have a common header and footer.
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.
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.
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.
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.
This is where you enter the general details of your event. The following fields are available.
- Title: The title of the event, a single line sumarey that will bedisplayed in the main diary window.
- Status: The Status of the event, Confirmed, Unnonfirmed or Cancelled
- 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!
- 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.
- Location: The location of the event. A real world address, telephone number or whatever...
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).
- 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.
- Choose TimeZone Popup. This will popup a window to allow you to choose the timezone from a TimeZone requester window.
- 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.
- DD FullMonthName (YY)YY
- DD MM YY
- DD MM (YY)YY
- DD AbreviatedMonthName (YY)YY
- 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 :-).
- 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.
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.
- Repeat type: A chooser gadget offering the available repeat options.
- Off - Event Doesn't reapeat, all other gadgets in this section are disabled
- Daily - Event repeats every day, at the same time.
- Weekly - Event repeats every week onj the same weekday at the same time
- Monthly - Event repeats on the same date each month, eg May 2st, June 2st, July 2nd etc, if the event occurs on the 29,30 or 31 and the month does not have enough days then the ewent occurs on the last day of the month.
- Yearly - Event occurs on same date each year. (Like a birthday....)
- Same Day Each Month - Event occurs on the same day of the week each month, eg every first Sunday, every second Thursday etc.
- 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.
- Repeat End Date: Sets the date after which no more repeats occur.
The final section displays any alarms set on the vent, and allows adding editing or deleting alarms.
- Add Alarm: Adds a new alarm, opens the Alarm editor window to set the details
- Edit Alarm: Edit the alarm currently slected in "R" the alarms list.
- Delete Alarm: Delete the currently selected alarm
- 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,
- Notify: Display a message on the screen, either via the RingHIO notifications server or via a requester class window.
- Sound: Play a sound sample
- Email: Send an email (only usable with remote CalDAV servers that support sending email notifications for ebvents).
- Action: Execute a command, program or script
- Set the Alarm type
- 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.
- Set the time offset the alarm triggers at, in days, hours and minutes.
- 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).
- Relative to end: if this is checked the alarm timing will be calculated relative to the end of the event, rather than the start.
- Alarm details: The fields in this section vary depending on the alarm type.
- Notify: The title and description to be displayed in the notification
can be set here. If they are left blank then the title and location from
the event are used. If Use Requester is chacked then the notification will
be displayed with a requester window, rather than a RingHIO notification.
Use this for notification you consider extra important and don't want to
miss. Requester Notifications block so are add to end of the larm list,
so that any sounds or commands that occur at the same time or before hand
may be executed.
- Sound: A file gadget enables you to choose a sound file to be played. Any file the datatypes system recognises will be suitable. The sound is played asynchrounously.
- Action: The command or script can be selected via the file gadget, and the arguments to be passed entered in a separate string gadget. A number of special sequences may be used to pass details of the event triggering the alarm
- %k: The event key, this can be used with the ARexx interface to get event details.
- %u: The url, the URL of the event on the remote CalDAV server if there is one.
- %t: The event title.
- %d: The event description.
Time Zone 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
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.
- SyncScript: This script is called periodically, or on demand from from the Syncing->Sync Diary menu item.
- 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
- 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 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:
- 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....
- Start AOrgansier diary, and load you old diary project from the menu.
- If your diary was created with a 1.x series version of AOrganiser, save your diary out to a new file, to ensure the project icon has the correct icon and tooltypes
- Start the Google Setup Wizard, it can be found in the Scripts/CalDAV directory. You can start it by simply double clicking on it's icon
- The wizard window will open and ask you to enter the name of the Calendar you wish to to sync to, this most usualy your primary calendar and will be named after you google account email address
- Once you have entered the name of the google calendar to sync to and pressed RETURN or TAB click on the "Request Authentication" button (which will have just enabled).
- An URLOpen requester will now open, choose a google capable browser from the list to open the URL (Odyssey recomended)
- Log into your google account and follow intructions in the browser
- Once you have given permission copy the long text string to the clip board, and paste into the Authentication Token: field in the wizard and press TAB.
- Click on the "Request Credtials" button.
- After a short delay the wizard should report that credentials have been granted
- Now click on Save Credentials, at this point the credentials needed to access your google diary are now saved into you diary, for future use. Also the needed script callbacks will be setup.
- First sync: After a short delay the SyncScript will run, this will download all events from the remote diary into your local diary, then upload all the exiting events. This may take a short while, maybe up to 60 seconds or so ig you have large amount of events in either of the calendars being linked.
- After the first sync a "sync-token" is stored in the diary, and aldo a "ctag", these can be chacked on subsequant syncs and only chnages since they were issued will be downloaded from the server
- Syncing a new AOrganiser diary:
You wish to create a fresh local copy of your remote google calendar.
- The procedure is much the same as the above but rather than load in an old diary, just start diary from it's program icon.
- Save the empty diary to the new location at which you wish to store the new diary
- Start the google wizard as described above and and follow through the steps, till you save the credentials and the wizard closes.
- First sync: Again after a short delay the first sync starts, this will behave very similarly to the above case, but as there are no local events to upload, it should run a little faster
- Again the "sync-token" and "ctag" will be saved into the diary to enable ecomnic syncing of only changes to the diary
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 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 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.
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. You're 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.
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.
- Return the template of the specified command
Load a new diary project.
- Append the events in the loaded diary to the currently loaded diary
- Supress the warning requester if the currently diary has been modifued
- The file name of the diary to be loaded. If omitted a file requester will open for the user to choose a file
Save the current diary to it's file.
- Specify a new file to save the diary too.
Save the diary to a new file.
- The file name of the diary to be loaded. If omitted a file requester will open for the user to choose a file
- Supress the warning requester if the current diary is modified.
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.
- The date and time that the event starts at, expressed as seconds since the Amiga epoch (1.1.1978). Overides other date time options.
- The date of the event expressed as a DateString, ie a localised date typically of the form DD MMM YYYY
- The start time of the event expressed as string in the form hh:mm
- The title or summary of the event, a single line of text
- 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
- Whether the event repeats. 0 means no repeat, 1 or higher sets the repeat frequency.
- The type of repeat expressed as a number
- Same Day Each Month
- Datestring indicating the time date the event should repeat till. Omitting means repeat forever
- Reapeat enddate expressed as seconds since the epoch
- The date / time the event ends expressed as seconds since the epoch
- The edn date of the event as a date string
- The end time expressed as hh:mm
- 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
- If set then update the event with matching unique ID
- 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.
- A single line string defining the location of the event. Usually geographic, but not required to be so.
- Name of the organiser of this event
- URL of the orgnaiser. (usually a mailto: URL)
- URL associated with the event. This is most usually the URL of the event on a CalDAV server
- Sequence level of the event. Any time the date / time and certain other attributes are changed the sequence level is incremented
- Time zone of the event in IANA format. Ie Europe/London , America/Chicago or Asia/Shanghai etc etc
- Status options are
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.
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 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.
- Choose event by it's "KEY" as returned by ADD or by NEXT etc.
- Choose event via it's Unique ID
- Choose event via it's URL
- Choose the event currently slected ion the GUI
- Look for the event on the deleted list, only KEY,UNIQUE and URL may be used with this option
- The field you wish to query, the value will be placed in RESULT
- 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.
- ALARMS: Number of alarms set.
Opens the Event Editor window for the chosen event.
- Choose event by KEY
- Choose event by UniqueID
- Choose event bu URL
- Choose currently selected event in GUI
- 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.
Get the Key for the next event in the event list.
- The key of the current event or 0 to get the first event in the list
Get the Key for the previous event in the event list.
- The key of the current event or 0 to get the last event in the list
Select the chosen event in the GUI.
- Choose the event to select via it's key.
Display the GUI, unhide, uniconify or bring to front as required
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.
- The key of the event to delete
- Supress warning requester
Display the specified date in the GUI.
- Specify date in seconds sunce the epoch, ie Amiga system time
- Specify date as a human readable string, using localised names for months etc.
- use todays date as the date to show
Display the specified event in the GUI
- Choose event by KEY
- Choose event by UniqueID
- Choose event bu URL
- Choose currently selected event in GUI
Retrieve global information about the diary.
- Specify the individual field that you want to retrive the value is placed in RESULT
- 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
Set some or all of the diary's global values.
- The field you wish to set, when setting individual attributes,
- A stem value to set multiple attributes, only those attributes added to teh stem will be set. See GETDIARYINFO for list of attributes
- The value of the attribute when setting via FIELD
Add an alarm to a given event, or modify an existing one.
- The key of the event to which you wish to add the alarm
- The key of the alrm you wish to modify, if omitted creates a new alarm
- The alarm time is absolute and not relative to the event timeing
- The Alarm is relative to the end of the event rather than it's start time
- 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
- 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
- Make this command active
- Make this command inactive
- mark this alarm as local, shouldn't be synced or overwritten by a sync script
- Mark this alarm as remote, ie it will be synced and remote changes will overwrite when synced
- 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
- 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
- Third attribute of the alarm, this value depends on the alrm type.
- DISPLAY: Use requester in non zero
- EMAIL: Recipient (unsupported at present)
- PROCEDURE: Run from ARexx if non zero
Delete a given alarm on an given event.
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
- The key for the event to be queried
- Look fr eent on the deleted list
- 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
Get information about a specific timezone.
- The timezone to be queried expressed in IANA form ie Europe/London if no timezone is specified the diaries current time zone is used.
- The specific field to be queried, value is returned in RESULT
- The stem var to place all the data in:
- 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
Set the busy pointer on the application.
Remove the busy pointer on the application.
Locks the GUI, which means that chnages to the diary do not trigger an update in the gadgets.
Unlock the GUI.
Force a GUI refresh, sometimes useful after the GUI has been locked for while as, unlocking does not by itself refresh.
Get the UTC offset for a given timezone, either at specific time, or the standard or daylight savings values.
- The time, in seconds since the epoch, local to the timezone, to find the UTCOfset for.
- Find the offset for the standard time
- Find the offset for daylight savings time
- Timezone to find the time for in IANA format
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:
Timezone argument is currently ignored.
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.
Search the diary with a range of conditions.
- Specify the start time of the search in seconds since the epoch, if omitted events are serach from the earliest possible time onwards
- 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
- As above but express the dates as "DateStrings"
- Limit the serach to events occuring "Today"
- Limit the serach to those events currently displayed
- Inlcude repeats in the search
- Stem to place the search results in
- Field to filter search result on:
- DOS Pattern to user as filter
- Reject matches rather than accepting matches
- Sort result by time, otherwise they arrive in "list order" which is arbitrary
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.
- Specify date as seconds since the epoch
- Specufy the date asn a Date String
- If set return a date string, otherwise return the date in terms of seconds since the epoch
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.
- CalDAV.event - provides an event object that allows import and export of events as VCalender files
- CalDAV.timezone - provides a timezone of object and some timezone manipulation utilities.
- CalDAV.amitime - provides some functions that enable easy working in Amiga times, rather than the unix times many python modules default to
- CalDAV.oauth2client - a back port of googles OAuth2 client library to python 2.5, also contains an embeded copy of their http2 library.
The following example scripts are provided:
- ReleaseGUI.rexx: The main CalDAV syncing scripts lock the GUI while in use, and attempt to trap errors and release the GUI on exit, very rarely an untrapable error occurs. You can use this script to get access to the GUI again. Also useful when debugging your own scripts
- SearchGUI.py: Provides a simple ProAction based GUI for searching the diary using AmigaDOS patterns. This is typically called from the Scripts menu.
- ShowDate.rexx: Simple example of how to show specific date. Can be used with AEons calendar util, to pop up AOrganiser when double clicking on the calendar
- ShowEvents.rexx: Example of how to iterate through the events in the diary.
- SimpleSearch.rexx: A simple command line search script
- CalDAV/ExportSelected.py: Export the currently selected event to a VCalendar file
- CalDAV/ImportICAL.py: Import and event from a ical/vcalendar file and handle duplications etc.