GcalManager: GNOME Calendar Reference Manual

## GcalManager GcalManager — The backend of GNOME Calendar |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GcalManager * | gcal_manager_new_with_settings ()
ESource * | gcal_manager_get_source ()
GList * | gcal_manager_get_sources ()
GList * | gcal_manager_get_sources_connected ()
ESource * | gcal_manager_get_default_source ()
void | gcal_manager_set_default_source ()
icaltimezone * | gcal_manager_get_system_timezone ()
void | gcal_manager_set_subscriber ()
void | gcal_manager_set_search_subscriber ()
void | gcal_manager_set_query ()
gchar * | gcal_manager_query_client_data ()
void | gcal_manager_refresh ()
gboolean | gcal_manager_is_client_writable ()
void | gcal_manager_create_event ()
void | gcal_manager_update_event ()
void | gcal_manager_remove_event ()
void | gcal_manager_move_event_to_source ()
gchar * | gcal_manager_add_source ()
void | gcal_manager_enable_source ()
void | gcal_manager_disable_source ()
void | gcal_manager_save_source ()
GList * | gcal_manager_get_events ()
gboolean | gcal_manager_get_loading ()
GoaClient * | gcal_manager_get_goa_client ()
GcalEvent * | gcal_manager_get_event_from_shell_search ()
void | gcal_manager_setup_shell_search ()
void | gcal_manager_set_shell_search_query ()
void | gcal_manager_set_shell_search_subscriber ()
gboolean | gcal_manager_shell_search_done ()
GList * | gcal_manager_get_shell_search_events ()

## Properties

ESource * | default-calendar | Read / Write
gboolean | loading | Read
GSettings * | settings | Read / Write / Construct Only

## Signals

void | query-completed | Run Last
void | source-added | Run Last
void | source-changed | Run Last
void | source-enabled | Run Last
void | source-removed | Run Last

## Types and Values

#define | GCAL_TYPE_MANAGER
| GcalManager

## Object Hierarchy

        GObject
        ╰── GcalManager

## Description

GcalManager is the backend of GNOME Calendar. It sets everything up, connects to the Online Accounts daemon, and manages the events and calendars.

## Functions

### gcal_manager_new_with_settings ()

    GcalManager *
    gcal_manager_new_with_settings (GSettings *settings);

Creates a new GcalManager with `settings` .

#### Parameters

settings | a GSettings |

#### Returns

a newly created GcalManager.

[transfer full]

### gcal_manager_get_source ()

    ESource *
    gcal_manager_get_source (GcalManager *manager,
                             const gchar *uid);

Retrieve a source according to it's UID. The source is referenced for thread-safety and must be unreferenced after user.

#### Parameters

manager | a GcalManager |
uid | the unique identifier of the source |

#### Returns

an ESource, or `NULL`.

[nullable][transfer full]

### gcal_manager_get_sources ()

    GList *
    gcal_manager_get_sources (GcalManager *manager);

Retrieve a list of the enabled sources used in the application.

#### Parameters

manager | a GcalManager |

#### Returns

a GList.

[nullable][transfer container][content-type ESource]

### gcal_manager_get_sources_connected ()

    GList *
    gcal_manager_get_sources_connected (GcalManager *manager);

Returns a GList with every source connected on the app, whether they are enabled or not.

#### Parameters

manager | a GcalManager |

#### Returns

a GList.

[nullable][transfer container][content-type ESource]

### gcal_manager_get_default_source ()

    ESource *
    gcal_manager_get_default_source (GcalManager *manager);

#### Parameters

manager | a GcalManager |

#### Returns

an ESource object. Free with `g_object_unref()`.

[transfer full]

### gcal_manager_set_default_source ()

    void
    gcal_manager_set_default_source (GcalManager *manager,
                                     ESource *source);

Sets the default calendar.

#### Parameters

manager | a GcalManager |
source | the new default source. |

### gcal_manager_get_system_timezone ()

    icaltimezone *
    gcal_manager_get_system_timezone (GcalManager *manager);

Retireves the default timezone.

#### Parameters

manager | a GcalManager |

#### Returns

the default timezone.

[transfer none]

### gcal_manager_set_subscriber ()

    void
    gcal_manager_set_subscriber (GcalManager *manager,
                                 ECalDataModelSubscriber *subscriber,
                                 time_t range_start,
                                 time_t range_end);

Sets the `subscriber` to show events between `range_start` and `range_end` .

#### Parameters

self | a GcalManager |
subscriber | a ECalDataModelSubscriber |
range_start | the start of the range |
range_end | the end of the range |

### gcal_manager_set_search_subscriber ()

    void
    gcal_manager_set_search_subscriber (GcalManager *manager,
                                        ECalDataModelSubscriber *subscriber,
                                        time_t range_start,
                                        time_t range_end);

Sets the `subscriber` to show events between `range_start` and `range_end` .

#### Parameters

self | a GcalManager |
subscriber | a ECalDataModelSubscriber |
range_start | the start of the range |
range_end | the end of the range |

### gcal_manager_set_query ()

    void
    gcal_manager_set_query (GcalManager *self,
                            const gchar *query);

Set the query terms of the ECalDataModel or clear it if `NULL` is passed

#### Parameters

self | A GcalManager instance |
query | query terms or `NULL`. | [nullable]

### gcal_manager_query_client_data ()

    gchar *
    gcal_manager_query_client_data (GcalManager *manager,
                                    ESource *source,
                                    const gchar *field);

Queries for a specific data field of the ECalClient

#### Returns

a string representing the retrieved value.

[nullable][transfer none]

### gcal_manager_refresh ()

    void
    gcal_manager_refresh (GcalManager *manager);

Forces a full refresh and synchronization of all available calendars.

#### Parameters

manager | a GcalManager |

### gcal_manager_is_client_writable ()

    gboolean
    gcal_manager_is_client_writable (GcalManager *manager,
                                     ESource *source);

Retrieves whether `source` is writable.

#### Parameters

manager | a GcalManager |
source | an ESource |

#### Returns

`TRUE` if `source` is writable, `FALSE` otherwise.

### gcal_manager_create_event ()

    void
    gcal_manager_create_event (GcalManager *manager,
                               GcalEvent *event);

Creates `event` .

#### Parameters

manager | a GcalManager |
event | a GcalEvent |

### gcal_manager_update_event ()

    void
    gcal_manager_update_event (GcalManager *manager,
                               GcalEvent *event);

Saves all changes made to `event` persistently.

#### Parameters

manager | a GcalManager |
event | a GcalEvent |

### gcal_manager_remove_event ()

    void
    gcal_manager_remove_event (GcalManager *manager,
                               GcalEvent *event);

Deletes `event` .

#### Parameters

manager | a GcalManager |
event | a GcalEvent |

### gcal_manager_move_event_to_source ()

    void
    gcal_manager_move_event_to_source (GcalManager *manager,
                                       GcalEvent *event,
                                       ESource *dest);

Moves `event` to `dest` calendar. This is a fail-safe operation: worst case, the user will have two duplicated events, and we guarantee to never loose any data.

#### Parameters

manager | a GcalManager |
event | a GcalEvent |
dest | the destination calendar |

### gcal_manager_add_source ()

    gchar *
    gcal_manager_add_source (GcalManager *manager,
                             const gchar *name,
                             const gchar *backend,
                             const gchar *color);

Add a new calendar by its URI. The calendar is enabled by default

#### Parameters

manager | a GcalManager |
base_uri | URI defining the ESourceGroup the client will belongs |
relative_uri | URI, relative to the base URI |
color | a string representing a color parseable for gdk_rgba_parse |

#### Returns

unique identifier of calendar's source, or `NULL`.

[nullable][transfer full]

### gcal_manager_enable_source ()

    void
    gcal_manager_enable_source (GcalManager *manager,
                                ESource *source);

Enable the given ESource.

#### Parameters

manager | a GcalManager |
source | the target ESource |

### gcal_manager_disable_source ()

    void
    gcal_manager_disable_source (GcalManager *manager,
                                 ESource *source);

Disable the given ESource.

#### Parameters

manager | a GcalManager |
source | the target ESource |

### gcal_manager_save_source ()

    void
    gcal_manager_save_source (GcalManager *manager,
                              ESource *source);

Commit the given ESource.

#### Parameters

manager | a GcalManager |
source | the target ESource |

### gcal_manager_get_events ()

    GList *
    gcal_manager_get_events (GcalManager *manager,
                             icaltimetype *range_start,
                             icaltimetype *range_end);

Returns a list with GcalEvent objects owned by the caller, the list and the objects. The components inside the list are owned by the caller as well.

#### Parameters

manager | a GcalManager |
start_date | the start of the dete range |
end_date | the end of the dete range |

#### Returns

a GList.

[nullable][transfer full][content-type GcalEvent]

### gcal_manager_get_loading ()

    gboolean
    gcal_manager_get_loading (GcalManager *self);

Retrieves whether `self` is still loading or not. Loading is complete when the Online Accounts client is retrieved, and all the calendars are loaded.

#### Parameters

self | a GcalManager |

#### Returns

`TRUE` if manager is still loading; `FALSE` otherwise

### gcal_manager_get_goa_client ()

    GoaClient *
    gcal_manager_get_goa_client (GcalManager *manager);

Retrieves the GoaClient connected by `self` .

#### Parameters

self | a GcalManager |

#### Returns

a GoaClient.

[transfer none]

### gcal_manager_get_event_from_shell_search ()

    GcalEvent *
    gcal_manager_get_event_from_shell_search
                                   (GcalManager *manager,
                                    const gchar *uuid);

Retrieves the GcalEvent with `uuid` .

#### Parameters

manager | a GcalManager |
uuid | the unique identier of the event |

#### Returns

a GcalEvent.

[nullable][transfer full]

### gcal_manager_setup_shell_search ()

    void
    gcal_manager_setup_shell_search (GcalManager *self,
                                     ECalDataModelSubscriber *subscriber);

Sets up the GNOME Shell search subscriber.

#### Parameters

manager | a GcalManager |
subscriber | an ECalDataModelSubscriber |

### gcal_manager_set_shell_search_query ()

    void
    gcal_manager_set_shell_search_query (GcalManager *manager,
                                         const gchar *query);

Set the query terms of the ECalDataModel used in the shell search

#### Parameters

manager | A GcalManager instance |
query | query string (an s-exp) |

### gcal_manager_set_shell_search_subscriber ()

    void
    gcal_manager_set_shell_search_subscriber
                                   (GcalManager *manager,
                                    ECalDataModelSubscriber *subscriber,
                                    time_t range_start,
                                    time_t range_end);

Subscribe `subscriber` to the shell data modal at the given range.

#### Parameters

self | a GcalManager |
subscriber | the ECalDataModelSubscriber to subscribe |
range_start | the start of the range |
range_end | the end of the range |

### gcal_manager_shell_search_done ()

    gboolean
    gcal_manager_shell_search_done (GcalManager *manager);

Retrieves whether the search at `manager` is done or not.

#### Parameters

self | a GcalManager |

#### Returns

`TRUE` if the search is finished.

### gcal_manager_get_shell_search_events ()

    GList *
    gcal_manager_get_shell_search_events (GcalManager *manager);

Retrieves all the events available for GNOME Shell search.

#### Parameters

self | a GcalManager |

#### Returns

a GList.

[nullable][transfer full][content-type GcalEvent]

## Types and Values

### GCAL_TYPE_MANAGER

    #define GCAL_TYPE_MANAGER                                        (gcal_manager_get_type ())

### GcalManager

    typedef struct _GcalManager GcalManager;

## Property Details

### The `“default-calendar”` property

      “default-calendar”         ESource *

The default calendar.

Flags: Read / Write

### The `“loading”` property

      “loading”                  gboolean

Whether the manager is loading or not.

Flags: Read

Default value: TRUE

### The `“settings”` property

      “settings”                 GSettings *

The settings.

Flags: Read / Write / Construct Only

## Signal Details

### The `“query-completed”` signal

    void
    user_function (GcalManager *gcalmanager,
                   gpointer     user_data)

Flags: Run Last

### The `“source-added”` signal

    void
    user_function (GcalManager *gcalmanager,
                   gpointer     arg1,
                   gboolean     arg2,
                   gpointer     user_data)

Flags: Run Last

### The `“source-changed”` signal

    void
    user_function (GcalManager *gcalmanager,
                   ESource     *arg1,
                   gpointer     user_data)

Flags: Run Last

### The `“source-enabled”` signal

    void
    user_function (GcalManager *gcalmanager,
                   ESource     *arg1,
                   gboolean     arg2,
                   gpointer     user_data)

Flags: Run Last

### The `“source-removed”` signal

    void
    user_function (GcalManager *gcalmanager,
                   gpointer     arg1,
                   gpointer     user_data)

Flags: Run Last