JanaStoreView

JanaStoreView — A store query interface

Synopsis

                    JanaStoreView;
enum                JanaStoreViewField;
void                jana_store_view_get_range           (JanaStoreView *self,
                                                         JanaTime **start,
                                                         JanaTime **end);
void                jana_store_view_set_range           (JanaStoreView *self,
                                                         JanaTime *start,
                                                         JanaTime *end);
JanaStoreViewMatch * jana_store_view_add_match          (JanaStoreView *self,
                                                         JanaStoreViewField field,
                                                         const gchar *data);
GList *             jana_store_view_get_matches         (JanaStoreView *self);
void                jana_store_view_remove_match        (JanaStoreView *self,
                                                         JanaStoreViewMatch *match);
void                jana_store_view_clear_matches       (JanaStoreView *self);
void                jana_store_view_start               (JanaStoreView *self);
JanaStore *         jana_store_view_get_store           (JanaStoreView *self);

Object Hierarchy

  GInterface
   +----JanaStoreView

Prerequisites

JanaStoreView requires GObject.

Signals

  "added"                                          : Run Last
  "modified"                                       : Run Last
  "progress"                                       : Run Last
  "removed"                                        : Run Last

Description

JanaStoreView is the interface for a query, or 'view' on a JanaStore. A store view has functions to query a particular time range of components.

Details

JanaStoreView

typedef struct _JanaStoreView JanaStoreView;

The JanaStoreView struct contains only private data.


enum JanaStoreViewField

typedef enum {
	JANA_STORE_VIEW_SUMMARY,
	JANA_STORE_VIEW_LOCATION,
	JANA_STORE_VIEW_DESCRIPTION,
	JANA_STORE_VIEW_AUTHOR,
	JANA_STORE_VIEW_RECIPIENT,
	JANA_STORE_VIEW_BODY,
	JANA_STORE_VIEW_CATEGORY,
	JANA_STORE_VIEW_ANYFIELD,
} JanaStoreViewField;

Enum values for different types of field to use in the jana_store_view_set_match() function. Using field values for incorrect JanaComponent types can have undefined results.

JANA_STORE_VIEW_SUMMARY

An event summary

JANA_STORE_VIEW_LOCATION

An event location

JANA_STORE_VIEW_DESCRIPTION

An event description

JANA_STORE_VIEW_AUTHOR

A note author

JANA_STORE_VIEW_RECIPIENT

A note recipient

JANA_STORE_VIEW_BODY

A note body

JANA_STORE_VIEW_CATEGORY

A component category

JANA_STORE_VIEW_ANYFIELD

Match any field

jana_store_view_get_range ()

void                jana_store_view_get_range           (JanaStoreView *self,
                                                         JanaTime **start,
                                                         JanaTime **end);

Retrieves the range over which this JanaStoreView is set to span. A NULL start or end indicate an unbounded range.

self :

A JanaStoreView

start :

Return location for the start of the view range, or NULL

end :

Return location for the end of the view range, or NULL

jana_store_view_set_range ()

void                jana_store_view_set_range           (JanaStoreView *self,
                                                         JanaTime *start,
                                                         JanaTime *end);

Sets the range for the JanaStoreView to span. A NULL parameter indicates that that end of the range should be unbounded (i.e. extended infinitely into the past or future). For event stores, this query will match against events that have occurences within this range; for note stores, this query will match against notes that were created or modified within this range.

self :

A JanaStoreView

start :

The start of the range, or NULL

end :

The end of the range, or NULL

jana_store_view_add_match ()

JanaStoreViewMatch * jana_store_view_add_match          (JanaStoreView *self,
                                                         JanaStoreViewField field,
                                                         const gchar *data);

Adds a matching query to the store view. This allows to search for components whose fields contain a particular string. The matching is done disregarding the case of letters in the string. field must contain a field that matches the component type being store by the underlying JanaStore, otherwise unexpected results may occur.

self :

A JanaStoreView

field :

The field to match against

data :

The matching string to use

Returns :

A JanaStoreViewMatch, representing the matching query.

jana_store_view_get_matches ()

GList *             jana_store_view_get_matches         (JanaStoreView *self);

Retrieves all matching queries that have been added to the store view. See jana_store_view_add_match().

self :

A JanaStoreView

Returns :

A newly allocated GList, containing all the JanaStoreViewMatch structures added to the store view. This list must be freed with g_list_free().

jana_store_view_remove_match ()

void                jana_store_view_remove_match        (JanaStoreView *self,
                                                         JanaStoreViewMatch *match);

Removes a matching query from a store view. match must have been returned by jana_store_view_add_match().

self :

A JanaStoreView

match :

A JanaStoreViewMatch

jana_store_view_clear_matches ()

void                jana_store_view_clear_matches       (JanaStoreView *self);

Removes all matching queries from a store view.

self :

A JanaStoreView

jana_store_view_start ()

void                jana_store_view_start               (JanaStoreView *self);

Starts the view. No signals will be emitted prior to calling this function.

self :

A JanaStoreView

jana_store_view_get_store ()

JanaStore *         jana_store_view_get_store           (JanaStoreView *self);

Retrieves the JanaStore that this view operates on.

self :

A JanaStoreView

Returns :

The JanaStore that this view operates on.

Signal Details

The "added" signal

void                user_function                      (JanaStoreView *store_view,
                                                        gpointer       components,
                                                        gpointer       user_data)       : Run Last

The ::added signal is emitted when new components become visible in the scope of the store view.

store_view :

the store view that received the signal

components :

A list of JanaComponents

user_data :

user data set when the signal handler was connected.

The "modified" signal

void                user_function                      (JanaStoreView *store_view,
                                                        gpointer       components,
                                                        gpointer       user_data)       : Run Last

The ::modified signal is emitted when components that were previously in view have been modified in some way.

store_view :

the store view that received the signal

components :

A list of JanaComponents

user_data :

user data set when the signal handler was connected.

The "progress" signal

void                user_function                      (JanaStoreView *store_view,
                                                        gint           percent,
                                                        gpointer       user_data)       : Run Last

The ::progress signal is emitted periodically as the query progresses. When the query is complete, percent will be 100.

store_view :

the store view that received the signal

percent :

Percentage completion of the current running query

user_data :

user data set when the signal handler was connected.

The "removed" signal

void                user_function                      (JanaStoreView *store_view,
                                                        gpointer       uids,
                                                        gpointer       user_data)       : Run Last

The ::removed signal is emitted when components that were previously in view have been removed from the underling JanaStore.

store_view :

the store view that received the signal

uids :

A list of uids

user_data :

user data set when the signal handler was connected.

See Also

#JanaStore