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.