MrpProject: Libplanner Reference Manual

MrpProject

MrpProject — Projects.

Functions

gboolean	(*MrpTaskTraverseFunc) ()
MrpProject *	mrp_project_new ()
gboolean	mrp_project_is_empty ()
gboolean	mrp_project_needs_saving ()
mrptime	mrp_project_get_project_start ()
void	mrp_project_set_project_start ()
gboolean	mrp_project_load ()
gboolean	mrp_project_save ()
gboolean	mrp_project_save_as ()
gboolean	mrp_project_export ()
gboolean	mrp_project_save_to_xml ()
gboolean	mrp_project_load_from_xml ()
void	mrp_project_close ()
const gchar *	mrp_project_get_uri ()
void	mrp_project_set_uri ()
MrpResource *	mrp_project_get_resource_by_name ()
GList *	mrp_project_get_resources ()
void	mrp_project_add_resource ()
void	mrp_project_remove_resource ()
MrpGroup *	mrp_project_get_group_by_name ()
GList *	mrp_project_get_groups ()
void	mrp_project_add_group ()
void	mrp_project_remove_group ()
MrpTask *	mrp_project_get_task_by_name ()
GList *	mrp_project_get_all_tasks ()
void	mrp_project_insert_task ()
void	mrp_project_remove_task ()
gboolean	mrp_project_move_task ()
MrpTask *	mrp_project_get_root_task ()
void	mrp_project_task_traverse ()
void	mrp_project_reschedule ()
gint	mrp_project_calculate_summary_duration ()
gint	mrp_project_calculate_task_work ()
GList *	mrp_project_get_properties_from_type ()
void	mrp_project_add_property ()
void	mrp_project_remove_property ()
gboolean	mrp_project_has_property ()
MrpProperty *	mrp_project_get_property ()
MrpCalendar *	mrp_project_get_root_calendar ()
MrpCalendar *	mrp_project_get_calendar ()
MrpDay *	mrp_project_get_calendar_day_by_id ()
void	mrp_project_set_block_scheduling ()
gboolean	mrp_project_get_block_scheduling ()

Properties

MrpCalendar *	calendar	Read / Write
MrpGroup *	default-group	Read / Write
char *	manager	Read / Write
char *	name	Read / Write
char *	organization	Read / Write
char *	phase	Read / Write
gpointer	phases	Read / Write
gint64	project-start	Read / Write

Signals

void	calendar-tree-changed	Run Last
void	day-added	Run Last
void	day-changed	Run Last
void	day-removed	Run Last
void	default-group-changed	Run Last
void	group-added	Run Last
void	group-removed	Run Last
void	loaded	Run Last
void	needs-saving-changed	Run Last
void	property-added	Run Last
void	property-changed	Run Last
void	property-removed	Run Last
void	resource-added	Run Last
void	resource-removed	Run Last
void	task-inserted	Run Last
void	task-moved	Run Last
void	task-removed	Run Last

Types and Values

struct	MrpProject
	MrpProjectPriv

Object Hierarchy

    GObject
    ╰── MrpObject
        ╰── MrpProject

Includes

#include <libplanner/mrp-project.h>

Description

A project has got some properties. One can add custom properties.

A project maintains a list of MrpGroup and can designates one as the default. If you specify a default group, every new MrpResource that you add will be placed in this group.

A project maintains a list of resources.

A project maintains a list of tasks. It can iterate over. Task management is delegated to a private MrpTaskManager class.

A project uses a calendar.

Day types belong to a project.

A project can define phases and switch from one to another.

Functions

MrpTaskTraverseFunc ()

gboolean
(*MrpTaskTraverseFunc) (MrpTask *task,
                        gpointer user_data);

A function to use with mrp_project_task_traverse(). task is the currently traversed task, and user_data is the user data passed to the mrp_project_task_traverse(). The traversal can be stopped by returning TRUE.

Parameters

task	an MrpTask
user_data	user data

Returns

TRUE if the traversal is to be stopped.

mrp_project_new ()

MrpProject *
mrp_project_new (MrpApplication *app);

Creates a new MrpProject.

Parameters

app

MrpApplication that creates the new project.

Returns

the MrpProject

mrp_project_is_empty ()

gboolean
mrp_project_is_empty (MrpProject *project);

Checks whether a project is empty.

Parameters

project

an MrpProject

Returns

TRUE if project is empty, otherwise FALSE

mrp_project_needs_saving ()

gboolean
mrp_project_needs_saving (MrpProject *project);

Checks if project needs saving

Parameters

project

an MrpProject

Returns

TRUE if project has been altered since last save, otherwise FALSE

mrp_project_get_project_start ()

mrptime
mrp_project_get_project_start (MrpProject *project);

Fetches the project start from project .

Parameters

project

an MrpProject

Returns

the project start

mrp_project_set_project_start ()

void
mrp_project_set_project_start (MrpProject *project,
                               mrptime start);

Set the project start.

Parameters

project	an MrpProject
start	project start time

mrp_project_load ()

gboolean
mrp_project_load (MrpProject *project,
                  const gchar *uri,
                  GError **error);

Loads a project stored at uri into project .

Parameters

project	an MrpProject
uri	the URI where project should be read from
error	location to store error, or `NULL`

Returns

Returns TRUE on success, otherwise FALSE.

mrp_project_save ()

gboolean
mrp_project_save (MrpProject *project,
                  gboolean force,
                  GError **error);

Saves a project.

Parameters

project	an MrpProject
force	overwrite changes done by someone else if necessary
error	location to store error, or `NULL`

Returns

TRUE on success, otherwise FALSE

mrp_project_save_as ()

gboolean
mrp_project_save_as (MrpProject *project,
                     const gchar *uri,
                     gboolean force,
                     GError **error);

Saves a project to a specific URI.

Parameters

project	an MrpProject
uri	URI to save to
force	overwrite an existing file if necessary
error	location to store error, or `NULL`

Returns

TRUE on success, otherwise FALSE

mrp_project_export ()

gboolean
mrp_project_export (MrpProject *project,
                    const gchar *uri,
                    const gchar *identifier,
                    gboolean force,
                    GError **error);

Exports a project to a specific URI. identifier is used to identify which module to use. It can be either the identifier string of a module or the mime type you whish to export to.

Parameters

project	an MrpProject
uri	URI to export to
identifier	string identifying which export module to use
force	overwrite an existing file if necessary
error	location to store error, or `NULL`

Returns

TRUE on success, otherwise FALSE.

mrp_project_save_to_xml ()

gboolean
mrp_project_save_to_xml (MrpProject *project,
                         gchar **str,
                         GError **error);

Saves a project as XML to a string buffer.

Parameters

project	an MrpProject
str	location to store XML string
error	location to store error, or `NULL`

Returns

TRUE on success, otherwise FALSE

mrp_project_load_from_xml ()

gboolean
mrp_project_load_from_xml (MrpProject *project,
                           const gchar *str,
                           GError **error);

Loads a project from XML data into project .

Parameters

project	an MrpProject
str	XML string with project data to read from
error	location to store error, or `NULL`

Returns

Returns TRUE on success, otherwise FALSE.

mrp_project_close ()

void
mrp_project_close (MrpProject *project);

Closes a project.

Parameters

project

an MrpProject

mrp_project_get_uri ()

const gchar *
mrp_project_get_uri (MrpProject *project);

Fetches the URI from project .

Parameters

project

an MrpProject

Returns

the URI of project

mrp_project_set_uri ()

void
mrp_project_set_uri (MrpProject *project,
                     const gchar *uri);

Sets the URI on project .

Parameters

project	an MrpProject
uri	an URI

mrp_project_get_resource_by_name ()

MrpResource *
mrp_project_get_resource_by_name (MrpProject *project,
                                  const gchar *name);

Retrieves the first resource in the list that match the name.

Parameters

project	an MrpProject
name	name to search for

Returns

an MrpResource or NULL if not found

mrp_project_get_resources ()

GList *
mrp_project_get_resources (MrpProject *project);

Fetches the list of resources in project . This list should not be freed and if caller needs to manipulate it, a copy needs to be made first.

Parameters

project

an MrpProject

Returns

the resource list of project

mrp_project_add_resource ()

void
mrp_project_add_resource (MrpProject *project,
                          MrpResource *resource);

Adds resource to the list of resources in project .

Parameters

project	an MrpProject
resource	MrpResource to add

mrp_project_remove_resource ()

void
mrp_project_remove_resource (MrpProject *project,
                             MrpResource *resource);

Removes resource from project .

Parameters

project	an MrpProject
resource	MrpResource to remove

mrp_project_get_group_by_name ()

MrpGroup *
mrp_project_get_group_by_name (MrpProject *project,
                               const gchar *name);

Retrieves the first group with name that matches name

Parameters

project	an MrpProject
name	a name to look for

Returns

an MrpGroup or NULL if not found

mrp_project_get_groups ()

GList *
mrp_project_get_groups (MrpProject *project);

Fetches the list of groups in project . The list should not be freed and if caller needs to manipulate it, a copy needs to be made first.

Parameters

project

an MrpProject

Returns

the group list of project

mrp_project_add_group ()

void
mrp_project_add_group (MrpProject *project,
                       MrpGroup *group);

Adds group to the list of groups in project .

Parameters

project	an MrpProject
group	MrpGroup to remove

mrp_project_remove_group ()

void
mrp_project_remove_group (MrpProject *project,
                          MrpGroup *group);

Removes group from project .

Parameters

project	an MrpProject
group	MrpGroup to remove

mrp_project_get_task_by_name ()

MrpTask *
mrp_project_get_task_by_name (MrpProject *project,
                              const gchar *name);

Retrieves the first task with name matching name . Uses task_traverse to traverse all tasks.

Parameters

project	an MrpProject
name	the name to look for

Returns

an MrpTask or NULL if not found.

mrp_project_get_all_tasks ()

GList *
mrp_project_get_all_tasks (MrpProject *project);

Returns a new list of the tasks in project . The caller needs to free the list with g_list_free(), but not the values in it.

Parameters

project

an MrpProject

Returns

a newly allocated list of the tasks

mrp_project_insert_task ()

void
mrp_project_insert_task (MrpProject *project,
                         MrpTask *parent,
                         gint position,
                         MrpTask *task);

Insert task in the task tree with parent at position among other children.

Parameters

project	an MrpProject
parent	MrpTask that will be parent to inserted task
position	position among children to insert task
task	MrpTask to insert

mrp_project_remove_task ()

void
mrp_project_remove_task (MrpProject *project,
                         MrpTask *task);

Removes task from the task tree in project .

Parameters

project	an MrpProject
task	MrpTask to remove

mrp_project_move_task ()

gboolean
mrp_project_move_task (MrpProject *project,
                       MrpTask *task,
                       MrpTask *sibling,
                       MrpTask *parent,
                       gboolean before,
                       GError **error);

Move the task in the task tree. If sibling is NULL task will be placed first among the children of parent if before is TRUE, otherwise it will be placed last. If sibling is set, task will be placed before or after sibling depending on the value of before .

Parameters

project	an MrpProject
task	MrpTask to move
sibling	MrpTask that `task` will be placed next to, can be `NULL`
parent	MrpTask the new parent
before	whether to put `task` before or after `sibling` .
error	location to store error, or NULL

Returns

TRUE on success, otherwise FALSE

mrp_project_get_root_task ()

MrpTask *
mrp_project_get_root_task (MrpProject *project);

Fetches the root task from project .

Parameters

project

an MrpProject

Returns

the root task

mrp_project_task_traverse ()

void
mrp_project_task_traverse (MrpProject *project,
                           MrpTask *root,
                           MrpTaskTraverseFunc func,
                           gpointer user_data);

Calls func on each task under root in the task tree. user_data is passed to func . If func returns TRUE, the traversal is stopped.

Parameters

project	an MrpProject
root	MrpTask indicates where traversing will begin.
func	the function to call for each task
user_data	user data passed to the function

mrp_project_reschedule ()

void
mrp_project_reschedule (MrpProject *project);

Reschedules the project, calculating task start/end/duration etc.

Parameters

project

an MrpProject

mrp_project_calculate_summary_duration ()

gint
mrp_project_calculate_summary_duration
                               (MrpProject *project,
                                MrpTask *task,
                                mrptime start,
                                mrptime finish);

Calculates the time needed to achieve the given start and finish time, ignoring allocated resources' calendars (summary tasks should ignore their own resource assignments)

Parameters

project	an MrpProject
task	an MrpTask
start	a start time, or if -1, the task start time is to be used
finish	a finish time

Returns

The calculated duration.

mrp_project_calculate_task_work ()

gint
mrp_project_calculate_task_work (MrpProject *project,
                                 MrpTask *task,
                                 mrptime start,
                                 mrptime finish);

Calculates the work needed to achieve the given start and finish time, with the allocated resources' calendards in consideration.

Parameters

project	an MrpProject
task	an MrpTask
start	a start time, or if -1, the task start time is to be used
finish	a finish time

Returns

The calculated work.

mrp_project_get_properties_from_type ()

GList *
mrp_project_get_properties_from_type (MrpProject *project,
                                      GType object_type);

Fetches a list of the properties belonging to project and applies to object_type . The list should not be freed and needs to be copied before modified.

Parameters

project	an MrpProject
object_type	a GType

Returns

The list of properties.

mrp_project_add_property ()

void
mrp_project_add_property (MrpProject *project,
                          GType object_type,
                          MrpProperty *property,
                          gboolean user_defined);

Add a custom property to project . The object_type specifies what kind of objects the property applies to. user_defined specifies whether the property is created by the user or by some plugin.

Parameters

project	an MrpProject
object_type	the owner type
property	an MrpProperty
user_defined	whether the property is defined through a user interface

mrp_project_remove_property ()

void
mrp_project_remove_property (MrpProject *project,
                             GType object_type,
                             const gchar *name);

Removes the property corresponding to object_type and name from project .

Parameters

project	an MrpProject
object_type	a GType specifying object type to remove property from
name	the name of the property

mrp_project_has_property ()

gboolean
mrp_project_has_property (MrpProject *project,
                          GType owner_type,
                          const gchar *name);

Checks if project has a property named name applying to object of type object_type .

Parameters

project	an MrpProperty
owner_type	a GType specifying object type look for property on
name	the name of the property

Returns

TRUE if property name exists on objects of type object_type

mrp_project_get_property ()

MrpProperty *
mrp_project_get_property (MrpProject *project,
                          const gchar *name,
                          GType object_type);

Fetches an MrpProperty that corresponds to name and object_type . This is mainly for language bindings and should not be used for other cases.

Parameters

project	an MrpProject
name	the name of the property
object_type	object type the property belongs to

Returns

An MrpProperty, if found, otherwise NULL.

mrp_project_get_root_calendar ()

MrpCalendar *
mrp_project_get_root_calendar (MrpProject *project);

Fetches the root calendar of project .

Parameters

project

an MrpProject

Returns

the root calendar of project

mrp_project_get_calendar ()

MrpCalendar *
mrp_project_get_calendar (MrpProject *project);

Fetches the calendar used by project .

Parameters

project

an MrpProject

Returns

the calendar used by project

mrp_project_get_calendar_day_by_id ()

MrpDay *
mrp_project_get_calendar_day_by_id (MrpProject *project,
                                    gint id);

Semi-private function. You most likely won't need this outside of Planner. Returns the day type associated with id .

Parameters

project	an MrpProject
id	an id

Returns

A day type.

mrp_project_set_block_scheduling ()

void
mrp_project_set_block_scheduling (MrpProject *project,
                                  gboolean block);

set block scheduling.

Parameters

project	an MrpProject.
block	new value.

mrp_project_get_block_scheduling ()

gboolean
mrp_project_get_block_scheduling (MrpProject *project);

get block scheduling.

Parameters

project

an MrpProject.

Returns

a boolean

Types and Values

struct MrpProject

struct MrpProject;

Object representing a project.

MrpProjectPriv

typedef struct _MrpProjectPriv MrpProjectPriv;

Property Details

The `“calendar”` property

  “calendar”                 MrpCalendar *

The calendar used in the project.

Owner: MrpProject

Flags: Read / Write

The `“default-group”` property

  “default-group”            MrpGroup *

Default group for new resources.

Owner: MrpProject

Flags: Read / Write

The `“manager”` property

  “manager”                  char *

The manager of the project.

Owner: MrpProject

Flags: Read / Write

Default value: ""

The `“name”` property

  “name”                     char *

The name of the project.

Owner: MrpProject

Flags: Read / Write

Default value: ""

The `“organization”` property

  “organization”             char *

The organization behind the project.

Owner: MrpProject

Flags: Read / Write

Default value: ""

The `“phase”` property

  “phase”                    char *

The phase the project is in.

Owner: MrpProject

Flags: Read / Write

Default value: ""

The `“phases”` property

  “phases”                   gpointer

The various phases the project can be in.

Owner: MrpProject

Flags: Read / Write

The `“project-start”` property

  “project-start”            gint64

The start date of the project.

Owner: MrpProject

Flags: Read / Write

Allowed values: [0,253402300799]

Default value: 0

Signal Details

The `“calendar-tree-changed”` signal

void
user_function (MrpProject  *project,
               MrpCalendar *calendar,
               gpointer     user_data)

emitted when calendar is changed.

Parameters

project	the object which received the signal.
calendar	the changed MrpCalendar.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“day-added”` signal

void
user_function (MrpProject *project,
               gpointer    day,
               gpointer    user_data)

emitted when day is added.

Parameters

project	the object which received the signal.
day	the added MrpDay.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“day-changed”` signal

void
user_function (MrpProject *project,
               gpointer    day,
               gpointer    user_data)

emitted when day is changed.

Parameters

project	the object which received the signal.
day	the changed MrpDay.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“day-removed”` signal

void
user_function (MrpProject *project,
               gpointer    day,
               gpointer    user_data)

emitted when day is removed.

Parameters

project	the object which received the signal.
day	the removed MrpDay.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“default-group-changed”` signal

void
user_function (MrpProject *project,
               MrpGroup   *group,
               gpointer    user_data)

emitted when default group changes.

Parameters

project	the object which received the signal.
group	the changed MrpGroup.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“group-added”` signal

void
user_function (MrpProject *project,
               MrpGroup   *group,
               gpointer    user_data)

emitted when group is added.

Parameters

project	the object which received the signal.
group	the added MrpGroup.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“group-removed”` signal

void
user_function (MrpProject *project,
               MrpGroup   *group,
               gpointer    user_data)

emitted when group is removed.

Parameters

project	the object which received the signal.
group	the removed MrpGroup.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“loaded”` signal

void
user_function (MrpProject *project,
               gpointer    user_data)

emitted when project is loaded.

Parameters

project	the object which received the signal.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“needs-saving-changed”` signal

void
user_function (MrpProject *project,
               gboolean    needs_saving,
               gpointer    user_data)

emitted when project need saving.

Parameters

project	the object which received the signal.
needs_saving	does `project` need saving?
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“property-added”` signal

void
user_function (MrpProject *project,
               glong       object_type,
               gpointer    property,
               gpointer    user_data)

emitted when property is added.

Parameters

project	the object which received the signal.
object_type	an MrpPropertyType.
property	the added MrpProperty.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“property-changed”` signal

void
user_function (MrpProject *project,
               gpointer    property,
               gpointer    user_data)

emitted when property is changed.

Parameters

project	the object which received the signal.
property	the changed MrpProperty.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“property-removed”` signal

void
user_function (MrpProject *project,
               gpointer    property,
               gpointer    user_data)

emitted when property is removed.

Parameters

project	the object which received the signal.
property	the removed MrpProperty.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“resource-added”` signal

void
user_function (MrpProject  *project,
               MrpResource *resource,
               gpointer     user_data)

emitted when resource is added.

Parameters

project	the object which received the signal.
resource	the added MrpResource.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“resource-removed”` signal

void
user_function (MrpProject  *project,
               MrpResource *resource,
               gpointer     user_data)

emitted when resource is removed.

Parameters

project	the object which received the signal.
resource	the removed MrpResource.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“task-inserted”` signal

void
user_function (MrpProject *project,
               MrpTask    *task,
               gpointer    user_data)

emitted when task is inserted.

Parameters

project	the object which received the signal.
task	the inserted MrpTask.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“task-moved”` signal

void
user_function (MrpProject *project,
               MrpTask    *task,
               gpointer    user_data)

emitted when task is moved.

Parameters

project	the object which received the signal.
task	the moved MrpTask.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“task-removed”` signal

void
user_function (MrpProject *project,
               MrpTask    *task,
               gpointer    user_data)

emitted when task is removed.

Parameters

project	the object which received the signal.
task	the removed MrpTask.
user_data	user data set when the signal handler was connected.

Flags: Run Last