# Orage

### Mickael Graf

`<korbinus@xfce.org>`

### Juha Kautto

`<juha@xfce.org>`

### Benedikt Meurer

`<benny@xfce.org>`

### Edscott Wilson Garcia

`<edscott@xfce.org>`

This manual describes `orage` version 4.4. Last updated: September 2006

Copyright © 2005-2006 Mickael Graf

## Introduction

Orage is a time-managing application that is part of the Xfce 4 Desktop Environment and features a calendar window, lists of events and reminders. It also provides an easy way to archive and manage your old appointments.

## Getting started

Orage is started by typing `orage` on the command line or in the run application window. You can also start it by clicking on the item `orage` in the submenu "Office" from the desktop menu. Another handy way of starting `orage` is to click button 1 on orageclock panel plugin.

But actually the first thing you should do is to adjust your preferences. At least before adding any appointments, you should set your local timezone.

Figure 1. Orage menu item in the desktop menu

When you run `orage`, you will first see the calendar window appearing.

## The calendar window

Figure 2. Default Calendar window

The calendar window provides you a menu bar giving access to different functions. Below that is a nice calendar showing the month, the year, day names, week numbers.

### The menu bar

The menubar contains four menus, which are the File, Edit, View, Help.

#### The File menu

Figure 3. File menu in the calendar window

The file menu contains five items:

- New: fire an appointment window (see below) for creating a new appointment;
- Open archive file...: fire a file selector for opening file containing old items;

  ### Warning

  This makes the selected file to act as your current active calendar file. It is possible to add, modify and remove appointments from it. You probably only want to take a look and return to your normal file (by closing archive file).

- Close archive file: close the previously opened file - greyed when no file opened;
- Close: close the calendar window, keeping the application running;
- Quit: close the opened windows and end the application;

#### The Edit menu

Figure 4. Edit menu in the calendar window

The Edit menu gives you access to the setting window, which will be presented later on.

#### The View menu

Figure 5. View menu in the calendar window

The View menu has two choices:

- View selected date: show the event list of currently selected date;
- Select today: set calendar's selected day to be today;

#### The Help menu

Figure 6. Help menu in the calendar window

The Help menu has also two choices:

- Help: show this help file;
- About: show information about the authors and license;

### The calendar

Calendar view presents you one month, which you can change by pressing the arrow beside the month name or the year number or using the mouse wheel. Days where you have appointments are marked as bold. One day is always selected and shown with a block. You can change the selected day by single clicking any day number. Double clicking a day number causes event-list window for that day to be activated.

## The eventlist window

Figure 7. Orage eventlist window

The eventlist (or appointment list as it is also called) window shows all activites that you have reserved for the day (date is shown in the window heading the format yyyy-mm-dd). On top of the window it gives you buttons to do actions. (All actions are also available in menus above the buttons.) This is your main activity window and you may want to keep it up all the day and even make it to appear on all workspaces or to be always on top of other windows.

### The button bar

There are 9 activity buttons in the button bar from left to right:

- New: start an appointment window for creating a new appointment for this day;
- Back: show previous day;
- Today: show today;
- Forward: show next day;
- Refresh: Redisplay this date. This window is usually refreshed automatically, but on certain special cases it may not show the latest changes. (Most common case is probably when you start editing an appointment from the alarm window instead from this eventlist window);
- Duplicate: start an appointment window for creating a new appointment for this day. But do not start from scratch, but copy all values from the active row in the appointment list below. Note that if you do not have any rows selected from the eventlist, this button does not do anything (but gives a g_warning, which you normally cannot see);
- Close: close this window;
- Clear: remove all appointments which start on the shown day. Note that it is possible to create repeating appointments in `orage` and if such an appointment is shown, but starts on an earlier date, it is NOT removed. (But repeating events will be removed if the first day is on this day.) Be carefull with this button! Before removing anything it asks for your verification, because it may remove many appointments. (Note that you can not delete a single appointment in this window; you have to go to the appointment window to do that);
- Day count: you can see more than one day in this window by setting this number to larger than 0. Each number means show one more day. (It causes the Time column in the event listing to show also the date.) Note however that each repeating appointment is shown only once (=first time) instead of everytime it happens.

### The eventlist

The event list shows all appointments happening on this day. Scrollbars will appear if there are more lines or longer lines than what can fit into the window. You can edit any appointment by double clicking the row. Each line has three fields:

- Time: the starting and ending times of the appointment (it shows the date only if more than one day is shown). If the event has passed, it is overstriked. Currently active appointments are shown with red colour and future appointments are bold. It is also possible to define special whole day appoinmtments and they always have a text "All day" instead of real start and end times.
- Flags: gives information about the appointment. (Note that the explanations are visible as a hint when you move your cursor into the event list.) There are three flags in order:
  - Alarm: what kind of action happens when alarm time passes. n means no alarm has been defined. A means that window is raised as an alarm and S means that in addition to the window, a sound is also played.
  - Repeat: how often is that appointment happening. n means no repeating so that this event only happens once. D means daily repeat, W weekly, M monthly and Y yearly.
  - Type: what kind of reservation is this. Two options: f means free so that the action is not reserving the time and it is possible to schedule more appointments at the same time and respectively B means busy, so that nothing else can not be done at this time. Note that current version of `orage` does not enforce these and the flag is only as a comment (in the future this may be enforced).
- Title: the heading of the appointment. Note that the whole title is shown, so you may want to avoid using too long titles to keep the view cleaner.

## The appointment window

The appointment window is used to add, edit and delete appointments. It is the most complex window in `orage`, but most fields still have good default values and are not mandatory. It has button bar (All actions are also available in menus above the buttons) and three tabs controlling basic settings and alarms and recurrence settings.

### The button bar

There are 5 activity buttons in the button bar from left to right:

- Save: store the appointment to the orage system. This causes also data validity checking.
- Save and close: like Save, but also closes the window.
- Revert: undo all changes done after previous save. Note that this button is active only after data has been changed.
- Duplicate: start creating new appointment and copy all values from the current activity into it. The new appointment is not created until you press Save.
- Delete: remove current appointment permanently from orage system.

### The general tab

Figure 8. Orage appointment window - general tab

In this tab, you define the contents of the appointment.

Title

  The title of the appointment. It appears in the event list and also in the alarm window and is listed at the header of this window. It should be a rather short summary of the appointment.

Location

  This field should describe where the event happens. It can be for example Home or Office or Paris depending on what kind of appointment you have. It is also possible to leave it empty. `orage` is not using it in any special way, nor is it visible anywhere else than here.

All day event

  Selecting this checkbox causes so called whole day appointment to be defined. These do not have start nor end time defined, but it is possible that the event lasts several days. These are special since they always have window type alarm defined and although it is possible to add separate alarm (in alarm tab), it is ignored and not even stored to the system. (no warning is given so this is a bit confusing.) The automatic alarm is raised when `orage` is started or date changes and the new day has this kind of event.

Start

  Defines the start time of the appointment. First, press the date button and choose the date from the calendar. After that you set the hour and minute using either your mouse wheel or clicking the small arrows. It is also possible to type the numbers directly to the fields. Hours go from 0 to 23 (24 is not allowed value).

  The last button is timezone. Default value for new appointments is your current timezone, which you have set in the preferences. It is recommended to use real timezones instead of floating. You should not mix floating with real timezones although it is possible. Floating means that time is not bound to any timezone, but varies according to current settings. Modifying either the default timezone or start timezone may cause floating values to change.

End

  Similar to Start, but defines naturally the ending time. Note that start and end timezones may be different (for example when you schedule a meeting in abroad you can set the starting time in your local timezone and the rest of the timings in thedestination timezone). Eventlist window always shows times in your local time.

Duration

  Often it is easier to set the appointment duration instead of ending time. You can do that by marking the first box here. It is not possible to have both end time and duration at the same time, so end time setting will be unavailable after you select duration. Maximum duration is 1000 days, which is almost three years. Note that although the minute selectionm jumps 5 minutes at a time, you can manually enter any number (just remember to tab out from the field, so that the value is read).

Availability

  What kind of reservation is this. There are two possiblities: Free means that the action is not reserving the time and it is possible to schedule more appointments at the same time and respectively Busy means that nothing else can not be done at this time. Note that current version of `orage` does not enforce these menings and the flag is only as a comment (in the future this may be checked).

Note

  Free format long text, where you can and should explain more the appointment. It is shown in the alarm window.

### The alarm tab

Figure 9. Orage appointment window - alarm tab

In this tab, you define the alarm for the appointment. `orage` supports two kinds of alarms: window and sound, but they both happen at the same time and sound is just an extra alarm; it is not possible to only raise sound alarm. window alarm is raised if any of the alarm timing numbers is non zero (in other words there is no special flag to set alarm; just define the time for it). Similarly sound alarm is raised if sound file has a value.

NOTE: this alarm setting has no effect on all day events; they always have only window type alarm set.

Alarm

  Define how much earlier (compared to the appointment starting time) the alarm(s) happens. If all numbers are zero, no alarm is raised for this appointment.

Sound

  Define the sound file to be played when the alarm fires. Leaving this empty disables sound alarm and putting any value enables it. Remember to define the actual play command in the preferences dialog. You should also test that your system can play the filetype you choose there. Simply start a terminal and test it using the command you specified and the the sound file.

Repeat alarm sound

  Set this check box if you want to hear the sound more than once. (Usually you want to check this.) Note that there is an internal counter, which stops the sound after 500 plays. Note also that when sound is repeating it is restarted after each 2 seconds. (Sound can be stopped in the alarm window, but that only prevents the next play to happen, it does not interrupt currently playing alarm, which you should remember when using long lasting soundfiles.)

### The recurrence tab

Figure 10. Orage appointment window - recurrence tab

In this tab you can define repeating appointments. Often it makes sense to define that the same appointment happens every day or every month instead of creating a new appointment for each event.

Complexity

  Default is Basic and that makes it possible to define frequency and limit of the appointment only. Often that is enough and these settings are very easy and fast to do even if you are not familiar with calendars and alarms. Selecting Advanced gives you more possibilities and makes it possible to build complex recurrent appointments like for example:

  - Every Monday, Tuesday, Wednesday, Thursday and Friday.
  - Every third week.
  - Last Tuesday on every second month.

Frequency

  This is the base repeating period. Default is no repeat (=None) and other possibilities are daily, weekly, monthly and yearly.

Interval (Advanced)

  Default value is 1 and it means every time as specified in the Frequency selections. 2 means every second time and 3 every third time etc. For example if you want to schedule your meeting to happen every third week, select Frequency = Weekly and set Interval to 3. (Starting time is selected in the General tab and next event happens exactly 3 weeks from that)

Limit

  `orage` allows you also to limit the repeating count:

  - Repeat forever: this is default and does not limit the number of occurrences at all.
  - Repeat n times: the appointment is scheduled exactly n times. After that it ends (but is not removed).
  - Repeat until date: you can select the last date when this event happens. Note that it still happens normally during this date.

Weekdays (Advanced)

  Default is that all days are checked, which means that the event happens normally every day. By removing any check, you prevent the appointment to happen on that day. In other words, your appointment only happens on checked weekdays. The most natural usage of this is to use it with Frequency = Daily. You may want to have a chat meeting for example each Monday and Wednesday. You can do this by selecting Frequency = Daily and by checking only Weekdays Mon and Wed.

  Selecting Weekly or Monthly actually causes the same thing. Deselecting any weekday for weekly or monthly or yearly repeating appointments causes all the remaining weekdays to become selected even though the original repeating selection only selects one day from the period. This is needed so that it is possible to schedule for example a meeting to happen every second week on Tuesday and Friday (Frequency = weekly, Interval = 2, Weekdays = Tue and Fri).

Which day (Advanced)

  This setting can only be used for monthly and yearly repeating events. It can be used to select which weekday from the month or year is selected. For example if you want to schedule your meeting to happen on the first Tuesday of every month, you can first select Frequency = Monthly and then check only Tuesday from Weekdays and finally set this "which day" number to be 1 (choose the number located below Tuesday). Negative numbers count backwards starting from the end of period and zero means that this setting is not used. Frequency = Yearly, weekdays = Thursday only clicked and which say = -2 means second last Thursday of the year.

## The preferences window

The preferences window is used to enter initial values for `orage`. You can define several display options, how old apppointments should be archived and what is the play command to be used for playing sound alarms and also you can set the local timezone for `orage`.

### The display tab

Figure 11. Orage preferences window - display tab

In this tab you can define visibility options for the main window of `orage`.

Calendar borders

  You can hide window borders and make the calendar window smaller by choosing Hidden option. This frees more space to your other applicatiosn from your workspace.

Calendar window

  This option defines where the main window is visible.

Calendar start

  It is possible to define that `orage` starts in the background or as minimized. This option only affects the start of `orage`.

### The archives tab

Figure 12. Orage preferences window - archives tab

`orage` does not delete appointments automatically, so usually your calendar file grows bigger and because of that `orage` gets slower and takes up more memory from the system. It is possible to define automatic archiving so that old appointments are moved from the active calendar file to passive history file. This helps to keep the active file smaller and the application in good shape. Archiving is enabled by setting the threshold to other than "never" value. Of course it is also possible to manually delete appointments, but that removes them permanently and you will not be able to find them later.

Unfortunately `orage` version 4.4 has no way to search or bring back appointments from the history file. This means that although the archived events are not lost, they vanish so that you can only access them with the not so perfect archive file method (or manually outside `orage`).

Note that `orage` also splits recurring appointments so that if the original start date is older than threshold, that appointment is added to the archive file and the starting date in the active calendar file is updated to contain only values more recent than threshold. This also saves time when `orage` is searching recurrent events.

Archive file

  This file will contain the archived appointments. It will grow, but since `orage` is not accessing it, that does not matter.

Archive threshold

  This enables archiving mode by setting it to other than "never" value. Choises are 3, 6 or 12 months.

### The sound tab

Figure 13. Orage preferences window - sound tab

In this tab you can define which sound command `orage` uses when playing sound files. try testing some common commands like play or aplay from terminal to see what works in your system. You probably do not want to use full version of totem or mplayer since they will cause a video window also to appear and that most probably is not what you want.

Basically it is possible to do other than sound commands also since `orage` really only starts this program and gives it the sound file as parameter. But this is not the intention of this feature.

### The timezone tab

Figure 14. Orage preferences window - timezone tab

You should always set the default timezone for `orage` It is possible to use also floating times, but then all times should be in floating form. It definitely is a bad idea to mix floating and timezone times. Floating times tend to move to follow any timezones they see...

## Undocumented Features

Some hidden options allow you to customize `orage` behaviour. You can find and change those in `~/.config/xfce4/orage/oragerc`. (note that the active calendar file is also localeted in this directory.) You must be carefull not to change the format of these files or `orage` may not start anymore. Undocumented settings are:

- Main Window Position: normally you do not want to change this. It is the location of calendar window in the screen. `orage` updates this automatically, so your setting will be overwritten.
- Event Window Size: normally you do not want to change this. It is the size of eventlist window in the screen. `orage` updates this automatically, so your setting will be overwritten.
- Show Main Window Menu: setting this to 0 causes the menubar from calendar window to vanish. If you never use the menu, you can save screenspace with this and using Calendar border option. Default value is 1 (=show the menu). Only 0 and 1 are valid values.
- Select Always Today: controls which day is selected after `orage` main calendar window is hidden and comes visible again (for example clicking orageclock panel plugin). Default value is 0, which means that previously selected day will remain selected. The other option is 1, which causes current date always being selected. Only 0 and 1 are valid values.
- Use Dynamic Icon: setting these x and y sizes to nonzero causes `orage` to use dynamic icon, which has real month day number in it. It also lists `orage` in the top and month name at the bottom if those fit in. `orage` tries to fit all those three pieces of information in the available icon size using proper fonts, but if there is not enough space, top and bottom texts can be omitted. Finally `orage` switches to static icon if not even the number fits into the icon. Good values to test with are 32 (like X=32 Y=32).
- Ical Week Start Day: tells what is the first day of week. But note, that it is only used in weekly repeating appointments. It will not change the calendar view anyway.

## Frequently Asked Questions

Some common questions and answers.

#### 1. Frequently Asked Questions

1.1. Why does my week start on Saturday?
1.2. How can I insert my ical file into orage?
1.3. I have found a bug in orage or would like to see a new feature. How can I inform that to the developers?

1.1.

Why does my week start on Saturday?

This really is a problem in your distro. You can check how your operating system reports these to GTK+ and hence to `orage`, which uses strictly gtk calendar widget and does not tune these settings itself. Command locale first_weekday shows which day is the first day in your system. Usually Sunday is day number 1, but that can be changed so check that with command locale day, which shows days starting from day number 1. You may try with different LANG enevironment variable settings and calendar view in `orage` should change accordingly. Log a new bug for `orage` if you think it is not working correctly. Look more information from Xfce bug 1237 or from Debian bug 215466

If you are adventurous, you can actually fix these yourself. You need to find your locale definition file (like fi_FI or fr_FR). locate is your friend here and helps finding it. After that you can check what the setting is: grep first_weekday fi_FI and change that if it is wrong and after that you need to recompile your locale database.

1.2.

How can I insert my ical file into `orage`?

This is not currently possible. It is planned in future versions.

1.3.

I have found a bug in `orage` or would like to see a new feature. How can I inform that to the developers?

You should file a bug into Xfce bugzilla or send an email to `<xfce4-dev@xfce.org>` Xfce development.