## MrpCalendar

MrpCalendar — represents a calendar in the project.

## Synopsis

    #include <libplanner/planner.h>

                        MrpCalendarPriv;
    struct              MrpCalendar;
                        MrpInterval;
    MrpCalendar *       mrp_calendar_new                    (const gchar *name,
                                                             MrpProject *project);
    MrpCalendar *       mrp_calendar_copy                   (const gchar *name,
                                                             MrpCalendar *calendar);
    MrpCalendar *       mrp_calendar_derive                 (const gchar *name,
                                                             MrpCalendar *parent);
    void                mrp_calendar_reparent               (MrpCalendar *new_parent,
                                                             MrpCalendar *child);
    void                mrp_calendar_remove                 (MrpCalendar *calendar);
    const gchar *       mrp_calendar_get_name               (MrpCalendar *calendar);
    void                mrp_calendar_set_name               (MrpCalendar *calendar,
                                                             const gchar *name);
    void                mrp_calendar_day_set_intervals      (MrpCalendar *calendar,
                                                             MrpDay *day,
                                                             GList *intervals);
    GList *             mrp_calendar_day_get_intervals      (MrpCalendar *calendar,
                                                             MrpDay *day,
                                                             gboolean check_ancestors);
    gint                mrp_calendar_day_get_total_work     (MrpCalendar *calendar,
                                                             MrpDay *day);
    MrpDay *            mrp_calendar_get_day                (MrpCalendar *calendar,
                                                             mrptime date,
                                                             gboolean check_ancestors);
    MrpDay *            mrp_calendar_get_default_day        (MrpCalendar *calendar,
                                                             gint week_day);
    void                mrp_calendar_set_default_days       (MrpCalendar *calendar,
                                                             gint week_day,
                                                             ...);
    void                mrp_calendar_set_days               (MrpCalendar *calendar,
                                                             mrptime date,
                                                             ...);
    MrpCalendar *       mrp_calendar_get_parent             (MrpCalendar *calendar);
    GList *             mrp_calendar_get_children           (MrpCalendar *calendar);
    MrpInterval *       mrp_interval_new                    (mrptime start,
                                                             mrptime end);
    MrpInterval *       mrp_interval_copy                   (MrpInterval *interval);
    MrpInterval *       mrp_interval_ref                    (MrpInterval *interval);
    void                mrp_interval_unref                  (MrpInterval *interval);
    void                mrp_interval_get_absolute           (MrpInterval *interval,
                                                             mrptime offset,
                                                             mrptime *start,
                                                             mrptime *end);

## Object Hierarchy

      GObject
       +----MrpObject
             +----MrpCalendar

## Properties

      "name"                     gchar*                : Read / Write
      "project"                  gpointer              : Read / Write

## Signals

      "calendar-changed"                               : Run Last

## Description

A calendar contains the information on working/nonworking time for resources. A calendar has a default week, specifying the day types (MrpDay) used for each day of the week by default.

Day types can be overriden so that a working day has another set of working time intervals per calendar. Certain dates can be overridden to use another day type as well.

## Details

### MrpCalendarPriv

    typedef struct _MrpCalendarPriv MrpCalendarPriv;

A private struct for internal use only. The definition of this structure is not publically available.

### struct MrpCalendar

    struct MrpCalendar;

Object representing a calendar in the project.

### MrpInterval

    typedef struct _MrpInterval MrpInterval;

Represents a time interval.

### mrp_calendar_new ()

    MrpCalendar *       mrp_calendar_new                    (const gchar *name,
                                                             MrpProject *project);

Creates a new MrpCalendar. The calendar will be empty so you need to set the default week and/or override days, see `mrp_calendar_set_default_days()` and `mrp_calendar_set_days()`.

`name` : | name of the calendar
`project` : | the MrpProject that the new calendar will belong to
Returns : | A new MrpCalendar.

### mrp_calendar_copy ()

    MrpCalendar *       mrp_calendar_copy                   (const gchar *name,
                                                             MrpCalendar *calendar);

Copies `calendar`, making the new calendar a base calendar, that does not have a parent.

`name` : | the name of the new calendar
`calendar` : | a MrpCalendar to copy
Returns : | a new MrpCalendar that is a copy of `calendar`.

### mrp_calendar_derive ()

    MrpCalendar *       mrp_calendar_derive                 (const gchar *name,
                                                             MrpCalendar *parent);

Derives a new calendar from `parent`. The new calendar will inherit all properties from `parent`, so if no days are overridden, the calendars will be identical.

`name` : | the name of the new calendar
`parent` : | the MrpCalendar to derive
Returns : | a new MrpCalendar that is derived from `parent`.

### mrp_calendar_reparent ()

    void                mrp_calendar_reparent               (MrpCalendar *new_parent,
                                                             MrpCalendar *child);

Changes the parent of `calendar` so that it inherits `new_parent`, instead of its old parent.

`new_parent` : | the new parent
`child` : | an MrpCalendar

### mrp_calendar_remove ()

    void                mrp_calendar_remove                 (MrpCalendar *calendar);

Removes `calendar` from the project. If the calendar is used by the project, a new calendar is set for the project. If the calendar has a parent, the parent is used, otherwise the first child of the root is used. For resources, the calendar is exchanged for the parent if one exists, otherwise the resource calendar is unset, so that the project default will be used.

`calendar` : | an MrpCalendar

### mrp_calendar_get_name ()

    const gchar *       mrp_calendar_get_name               (MrpCalendar *calendar);

Retrieves the name of the calendar.

`calendar` : | an MrpCalendar
Returns : | the calendar name.

### mrp_calendar_set_name ()

    void                mrp_calendar_set_name               (MrpCalendar *calendar,
                                                             const gchar *name);

Sets the name of the calendar.

`calendar` : | an MrpCalendar
`name` : | the new name

### mrp_calendar_day_set_intervals ()

    void                mrp_calendar_day_set_intervals      (MrpCalendar *calendar,
                                                             MrpDay *day,
                                                             GList *intervals);

Overrides the working time for the day type `day` when used in `calendar`.

`calendar` : | an MrpCalendar
`day` : | an MrpDay
`intervals` : | list of MrpInterval to set for the specified day

### mrp_calendar_day_get_intervals ()

    GList *             mrp_calendar_day_get_intervals      (MrpCalendar *calendar,
                                                             MrpDay *day,
                                                             gboolean check_ancestors);

Retrieves the working time for the given day/calendar combination. If `check_ancestors` is `TRUE`, the calendar hierarchy is searched until a calendar that has set the working time for this day type is found. If `FALSE`, the returned list will be empty if there is no explicit working time set for `calendar`.

`calendar` : | an MrpCalendar
`day` : | an MrpDay
`check_ancestors` : | specifies if the whole calendar hierarchy should be checked
Returns : | List of MrpInterval, specifying the working time for `day`.

### mrp_calendar_day_get_total_work ()

    gint                mrp_calendar_day_get_total_work     (MrpCalendar *calendar,
                                                             MrpDay *day);

Calculates the total amount of work for `day` in `calendar`.

`calendar` : | an MrpCalendar
`day` : | an MrpDay
Returns : | the amount of work in seconds.

### mrp_calendar_get_day ()

    MrpDay *            mrp_calendar_get_day                (MrpCalendar *calendar,
                                                             mrptime date,
                                                             gboolean check_ancestors);

Retrieves the day type for the given date and calender. If `check_ancestors` is `TRUE`, the parent and grandparent, and so on, is searched if `calendar` does not have an overridden day type for the specified date.

`calendar` : | an MrpCalendar
`date` : | an mrptime
`check_ancestors` : | specifies if the whole calendar hierarchy should be checked
Returns : | An MrpDay.

### mrp_calendar_get_default_day ()

    MrpDay *            mrp_calendar_get_default_day        (MrpCalendar *calendar,
                                                             gint week_day);

Retrieves the default day for `calendar`.

`calendar` : | an MrpCalendar
`week_day` : | integer in the range 0 - 6, where 0 is Sunday
Returns : | default MrpDay.

### mrp_calendar_set_default_days ()

    void                mrp_calendar_set_default_days       (MrpCalendar *calendar,
                                                             gint week_day,
                                                             ...);

Sets days in the default week for `calendar`. Those are the days that are used as fallback is a date is not overridden.

`calendar` : | an MrpCalendar
`week_day` : | integer in the range 0 - 6, where 0 is Sunday
`...` : | MrpDay followed by more week day/MrpDay pairs, terminated by -1

### mrp_calendar_set_days ()

    void                mrp_calendar_set_days               (MrpCalendar *calendar,
                                                             mrptime date,
                                                             ...);

Overrides specific dates in `calendar`, setting the type of day to use for those dates.

`calendar` : | an MrpCalendar
`date` : | an mrptime
`...` : | MrpDay followed by more mrptime/MrpDay pairs, terminated by -1

### mrp_calendar_get_parent ()

    MrpCalendar *       mrp_calendar_get_parent             (MrpCalendar *calendar);

Retrieves the parent calendar of `calendar`. The parent is the calendar that a calendar falls back to if a date or day type is not overridden.

`calendar` : | an MrpCalendar
Returns : | The parent calendar.

### mrp_calendar_get_children ()

    GList *             mrp_calendar_get_children           (MrpCalendar *calendar);

Retreives a list of the children, i.e. the calenderas that are immediately derived from `calendar`.

`calendar` : | an MrpCalendar
Returns : | List of `calendar`'s children.

### mrp_interval_new ()

    MrpInterval *       mrp_interval_new                    (mrptime start,
                                                             mrptime end);

Creates a new MrpInterval ranging from `start` to `end`.

`start` : | an mrptime specifying the start of the interval
`end` : | an mrptime specifying the end of the interval
Returns : | The newly created interval.

### mrp_interval_copy ()

    MrpInterval *       mrp_interval_copy                   (MrpInterval *interval);

Copies `interval`.

`interval` : | an MrpInterval
Returns : | The copied interval.

### mrp_interval_ref ()

    MrpInterval *       mrp_interval_ref                    (MrpInterval *interval);

Increases the reference count on `interval`.

`interval` : | an MrpInterval
Returns : | The interval.

### mrp_interval_unref ()

    void                mrp_interval_unref                  (MrpInterval *interval);

Decreases the reference count on `interval`. When the count goes to 0, the interval is freed.

`interval` : | an MrpInterval

### mrp_interval_get_absolute ()

    void                mrp_interval_get_absolute           (MrpInterval *interval,
                                                             mrptime offset,
                                                             mrptime *start,
                                                             mrptime *end);

Retrieves the start and end time of interval, with an optional `offset`.

`interval` : | an MrpInterval
`offset` : | the offset to add to start and end
`start` : | location to store start time, or `NULL`
`end` : | location to store end time, or `NULL`

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write

The name of the calendar.

Default value: "empty"

### The `"project"` property

      "project"                  gpointer              : Read / Write

The project this calendar belongs to.

## Signal Details

### The `"calendar-changed"` signal

    void                user_function                      (MrpCalendar *mrpcalendar,
                                                            gpointer     user_data)        : Run Last

`mrpcalendar` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.