![]() |
![]() |
![]() |
Osso Addressbook Reference Manual | ![]() |
---|---|---|---|---|
#define OSSO_ABOOK_CONTACT_FIELD_GROUP_STEP gboolean (*OssoABookContactFieldPredicate) (OssoABookContactField *field, gpointer user_data); enum OssoABookContactFieldFlags; OssoABookContactField; OssoABookContactField* osso_abook_contact_field_new_full (GHashTable *message_map, OssoABookContact *master_contact, OssoABookContact *roster_contact, EVCardAttribute *attribute); OssoABookContactField* osso_abook_contact_field_new (GHashTable *message_map, OssoABookContact *master_contact, EVCardAttribute *attribute); GHashTable* osso_abook_contact_field_get_message_map (OssoABookContactField *field); void osso_abook_contact_field_set_message_map (OssoABookContactField *field, GHashTable *mapping); const char* osso_abook_contact_field_get_name (OssoABookContactField *field); const char* osso_abook_contact_field_get_path (OssoABookContactField *field); OssoABookContactFieldFlags osso_abook_contact_field_get_flags (OssoABookContactField *field); OssoABookContactField* osso_abook_contact_field_get_parent (OssoABookContactField *field); GList* osso_abook_contact_field_get_children (OssoABookContactField *field); gboolean osso_abook_contact_field_has_children (OssoABookContactField *field); EVCardAttribute* osso_abook_contact_field_get_attribute (OssoABookContactField *field); EVCardAttribute* osso_abook_contact_field_get_borrowed_attribute (OssoABookContactField *field); GList* osso_abook_contact_field_get_secondary_attributes (OssoABookContactField *field); const char* osso_abook_contact_field_get_display_title (OssoABookContactField *field); const char* osso_abook_contact_field_get_secondary_title (OssoABookContactField *field); const char* osso_abook_contact_field_get_display_value (OssoABookContactField *field); const char* osso_abook_contact_field_get_icon_name (OssoABookContactField *field); int osso_abook_contact_field_get_sort_weight (OssoABookContactField *field); OssoABookContact* osso_abook_contact_field_get_master_contact (OssoABookContactField *field); OssoABookContact* osso_abook_contact_field_get_roster_contact (OssoABookContactField *field); McAccount* osso_abook_contact_field_get_account (OssoABookContactField *field); GList* osso_abook_contact_field_get_actions_full (OssoABookContactField *field, gboolean button); GList* osso_abook_contact_field_get_actions (OssoABookContactField *field); McAccount* osso_abook_contact_field_action_request_account (OssoABookContactFieldAction *action, GtkWindow *parent, gboolean *aborted); gboolean osso_abook_contact_field_action_start (OssoABookContactFieldAction *action, GtkWindow *parent); gboolean osso_abook_contact_field_action_start_with_callback (OssoABookContactFieldAction *action, GtkWindow *parent, OssoABookContactActionStartCb callback, gpointer callback_data); OssoABookContactFieldAction* osso_abook_contact_field_action_ref (OssoABookContactFieldAction *action); void osso_abook_contact_field_action_unref (OssoABookContactFieldAction *action); OssoABookContactAction osso_abook_contact_field_action_get_action (OssoABookContactFieldAction *action); OssoABookContactField* osso_abook_contact_field_action_get_field (OssoABookContactFieldAction *action); GtkWidget* osso_abook_contact_field_action_get_widget (OssoABookContactFieldAction *action); McProfile* osso_abook_contact_field_action_get_profile (OssoABookContactFieldAction *action); gboolean osso_abook_contact_field_action_is_basic (OssoABookContactFieldAction *action); GtkWidget* osso_abook_contact_field_create_button (OssoABookContactField *field, const char *title, const char *icon_name); GtkWidget* osso_abook_contact_field_get_label_widget (OssoABookContactField *field); GtkWidget* osso_abook_contact_field_get_editor_widget (OssoABookContactField *field); gboolean osso_abook_contact_field_has_editor_widget (OssoABookContactField *field); gboolean osso_abook_contact_field_is_readonly (OssoABookContactField *field); gboolean osso_abook_contact_field_is_bound_im (OssoABookContactField *field); gboolean osso_abook_contact_field_is_modified (OssoABookContactField *field); gboolean osso_abook_contact_field_is_empty (OssoABookContactField *field); gboolean osso_abook_contact_field_is_mandatory (OssoABookContactField *field); void osso_abook_contact_field_set_mandatory (OssoABookContactField *field, gboolean mandatory); gboolean osso_abook_contact_field_activate (OssoABookContactField *field); int osso_abook_contact_field_cmp (OssoABookContactField *a, OssoABookContactField *b); GList* osso_abook_contact_field_list_supported_fields (GHashTable *message_map, OssoABookContact *master_contact, OssoABookContactFieldPredicateaccept_field , gpointer user_data);
"attribute" gpointer : Read / Write / Construct Only "display-title" gchar* : Read "display-value" gchar* : Read "editor-widget" GtkWidget* : Read "flags" OssoABookContactFieldFlags : Read / Write "icon-name" gchar* : Read "label-widget" GtkWidget* : Read "master-contact" OssoABookContact* : Read / Write / Construct Only "message-map" GHashTable* : Read / Write "modified" gboolean : Read "name" gchar* : Read "roster-contact" OssoABookContact* : Read / Write / Construct Only "sort-weight" gint : Read
This class is an representation of an attribute that describes a contact. It contains UI widgets for displaying and editing the attribute.
OssoABookContactFields can have heirarchical relationships. For example, creating a OssoABookContactField for an address will result in several child fields created as well: one for each sub-component of the address (e.g. one for street address, one for post code, one for city, etc).
It's unlikely that third-party applications will need to use this class at all, it is mostly provided for use by the addressbook itself, and can be safely ignored by other applications.
gboolean (*OssoABookContactFieldPredicate) (OssoABookContactField *field, gpointer user_data);
The signature of a function that can be used to select or reject fields in
osso_abook_contact_field_list_supported_fields()
typedef enum { OSSO_ABOOK_CONTACT_FIELD_FLAGS_NONE = (0), OSSO_ABOOK_CONTACT_FIELD_FLAGS_HOME = (1 << 0), OSSO_ABOOK_CONTACT_FIELD_FLAGS_WORK = (1 << 1), OSSO_ABOOK_CONTACT_FIELD_FLAGS_CELL = (1 << 2), OSSO_ABOOK_CONTACT_FIELD_FLAGS_VOICE = (1 << 3), OSSO_ABOOK_CONTACT_FIELD_FLAGS_OTHER = (1 << 4), OSSO_ABOOK_CONTACT_FIELD_FLAGS_DEVICE_MASK = (OSSO_ABOOK_CONTACT_FIELD_FLAGS_CELL | OSSO_ABOOK_CONTACT_FIELD_FLAGS_VOICE), OSSO_ABOOK_CONTACT_FIELD_FLAGS_USAGE_MASK = (OSSO_ABOOK_CONTACT_FIELD_FLAGS_HOME | OSSO_ABOOK_CONTACT_FIELD_FLAGS_WORK), OSSO_ABOOK_CONTACT_FIELD_FLAGS_TYPE_MASK = (OSSO_ABOOK_CONTACT_FIELD_FLAGS_DEVICE_MASK | OSSO_ABOOK_CONTACT_FIELD_FLAGS_USAGE_MASK | OSSO_ABOOK_CONTACT_FIELD_FLAGS_OTHER), OSSO_ABOOK_CONTACT_FIELD_FLAGS_SINGLETON = (1 << 10), OSSO_ABOOK_CONTACT_FIELD_FLAGS_MANDATORY = (1 << 11), OSSO_ABOOK_CONTACT_FIELD_FLAGS_DYNAMIC = (1 << 12), OSSO_ABOOK_CONTACT_FIELD_FLAGS_NO_LABEL = (1 << 13), OSSO_ABOOK_CONTACT_FIELD_FLAGS_DETAILED = (1 << 14), } OssoABookContactFieldFlags;
A set of flags that describe various properties about a OssoABookContactField
OssoABookContactField* osso_abook_contact_field_new_full (GHashTable *message_map, OssoABookContact *master_contact, OssoABookContact *roster_contact, EVCardAttribute *attribute);
Creates a new OssoABookContactField to represent the specified attribute
message_map : |
a map from generic ids to contextual ids (see
osso_abook_message_map_new() )
|
master_contact : |
the master contact associated with this field, if any |
roster_contact : |
the roster contact associated with this field, if any |
attribute : |
the EVCardAttribute represented by this field |
Returns : | a new OssoABookContactField |
OssoABookContactField* osso_abook_contact_field_new (GHashTable *message_map, OssoABookContact *master_contact, EVCardAttribute *attribute);
Creates a new OssoABookContactField to represent the specified attribute
.
This constructor can be used if the field is not relevant to a particular
roster contact.
message_map : |
a map from generic ids to contextual ids (see
osso_abook_message_map_new() )
|
master_contact : |
the master contact associated with this field, if any |
attribute : |
the EVCardAttribute represented by this field |
Returns : | a new OssoABookContactField |
GHashTable* osso_abook_contact_field_get_message_map (OssoABookContactField *field);
Retrieve the message map for field
field : |
a OssoABookContactField |
Returns : | the contact field's message map |
void osso_abook_contact_field_set_message_map (OssoABookContactField *field, GHashTable *mapping);
Set the message map for a OssoABookContactField
field : |
a OssoABookContactField |
map : |
the new message map for field
|
const char* osso_abook_contact_field_get_name (OssoABookContactField *field);
Get the name of the attribute represented by field
field : |
a OssoABookContactField |
Returns : | the name of the contact field |
const char* osso_abook_contact_field_get_path (OssoABookContactField *field);
Gets the heirarchical path for field
. The format of the path string is
something like:
parentfieldname.thisfieldname
field : |
a OssoABookContactField |
Returns : | the path for field . This string is owned by the field and should
not be freed
|
OssoABookContactFieldFlags osso_abook_contact_field_get_flags (OssoABookContactField *field);
Gets the flags associated with field
field : |
a OssoABookContactField |
Returns : | the field's flags |
OssoABookContactField* osso_abook_contact_field_get_parent (OssoABookContactField *field);
Gets the parent field for field
field : |
a OssoABookContactField |
Returns : | field 's parent
|
GList* osso_abook_contact_field_get_children (OssoABookContactField *field);
Gets the list of children for field
field : |
a OssoABookContactField |
Returns : | a list of OssoABookContactFields, or NULL if field has no
children. The list and its contents are owned by field , and should not be
freed
|
gboolean osso_abook_contact_field_has_children (OssoABookContactField *field);
Checks whether field
has any child fields
field : |
a OssoABookContactField |
Returns : | TRUE if field has children, else FALSE
|
EVCardAttribute* osso_abook_contact_field_get_attribute (OssoABookContactField *field);
Gets the EVCardAttribute that is backing this field
.
field : |
a OssoABookContactField |
Returns : | the backing EVCardAttribute. The attribute is owned by field .
|
EVCardAttribute* osso_abook_contact_field_get_borrowed_attribute (OssoABookContactField *field);
Generally an OssoABookContactField will operate on a copy of the backing EVCardAttribute, but this function will return the real backing EVCardAttribute.
field : |
an OssoABookContactField |
Returns : | the backing EVCardAttribute, owned by field
|
GList* osso_abook_contact_field_get_secondary_attributes (OssoABookContactField *field);
Gets a list of all secondary attributes for field
. A secondary attribute is
an attribute that is automatically generated from the original attribute.
For instance, the vcard attribute FN
is automatically generated from the
vcard attribute N
field : |
a OssoABookContactField |
Returns : | a list of EVCardAttributes. The list is owned by field .
|
const char* osso_abook_contact_field_get_display_title (OssoABookContactField *field);
Gets a string to be used as a display title for field
field : |
a OssoABookContactField |
Returns : | the display title. This string is owned by field
|
const char* osso_abook_contact_field_get_secondary_title (OssoABookContactField *field);
For fields with a OSSO_ABOOK_CONTACT_FIELD_FLAGS_DETAILED
flag, gets the
secondary title.
field : |
a OssoABookContactField |
Returns : | the secondary title or NULL . This string is owned by field
|
const char* osso_abook_contact_field_get_display_value (OssoABookContactField *field);
Gets the value of field
as a displayable string
field : |
a OssoABookContactField |
Returns : | the value of field . The string is owned by field
|
const char* osso_abook_contact_field_get_icon_name (OssoABookContactField *field);
Gets the icon name for field
field : |
a OssoABookContactField |
Returns : | a icon name. The string is owned by field
|
int osso_abook_contact_field_get_sort_weight (OssoABookContactField *field);
Gets the sort weight for field
. The sort weight determines the display
order of attributes in the contact starter and contact editor. Higher values
are sorted first.
field : |
a OssoABookContactField |
Returns : | the sort weight |
OssoABookContact* osso_abook_contact_field_get_master_contact (OssoABookContactField *field);
Gets the master contact associated with field
.
field : |
a OssoABookContactField |
Returns : | the master contact, if any. The contact is owned by field .
|
OssoABookContact* osso_abook_contact_field_get_roster_contact (OssoABookContactField *field);
Gets the roster contact associated with field
.
field : |
a OssoABookContactField |
Returns : | the roster contact, if any. The contact is owned by field .
|
McAccount* osso_abook_contact_field_get_account (OssoABookContactField *field);
Gets the account associated with field
, if any.
field : |
a OssoABookContactField |
Returns : | a McAccount or NULL . The account is owned by field
|
GList* osso_abook_contact_field_get_actions_full (OssoABookContactField *field, gboolean button);
Gets the list of actions associated with field
based on the interactivity
mode of field
. If button
is TRUE
, returns the list of actions when field
is interactive. if button
is FALSE
, returns the list of actions when
field
is non-interactive
field : |
a OssoABookContactField |
button : |
whether the field should be interactive or not |
Returns : | a newly-allocated list of OssoABookContactFieldActions. The list and its contents are owned by the caller and should be freed when no longer needed |
GList* osso_abook_contact_field_get_actions (OssoABookContactField *field);
Gets a list of actions that can be performed for this field. Actions can be
activated with osso_abook_contact_field_action_start()
or
osso_abook_contact_field_action_start_with_callback()
.
field : |
a OssoABookContactField |
Returns : | a newly-allocated list of OssoABookContactFieldActions. The list and its contents are owned by the caller and should be freed when no longer needed |
McAccount* osso_abook_contact_field_action_request_account (OssoABookContactFieldAction *action, GtkWindow *parent, gboolean *aborted);
Get an account to associate with the specified action
. If more than one
account matches, presents a dialog to the user prompting them to choose
between the available options.
action : |
an OssoABookContactFieldAction |
parent : |
an optional parent GtkWindow to make dialogs transient for |
aborted : |
return location to report whether the action was aborted |
Returns : | an McAccount or NULL . Caller owns a reference.
|
gboolean osso_abook_contact_field_action_start (OssoABookContactFieldAction *action, GtkWindow *parent);
Activates the specified action
action : |
a OssoABookContactFieldAction |
parent : |
an optional parent GtkWindow to make dialogs transient for |
Returns : | TRUE on success, FALSE otherwise
|
gboolean osso_abook_contact_field_action_start_with_callback (OssoABookContactFieldAction *action, GtkWindow *parent, OssoABookContactActionStartCb callback, gpointer callback_data);
Activates the specified action
and calls callback
when complete.
action : |
a OssoABookContactFieldAction |
parent : |
an optional parent GtkWindow to make dialogs transient for |
callback : |
function to call when action is started |
callback_data : |
data to pass to callback
|
Returns : | TRUE on success, FALSE otherwise
|
OssoABookContactFieldAction* osso_abook_contact_field_action_ref (OssoABookContactFieldAction *action);
Takes a reference on action
action : |
a OssoABookContactFieldAction |
Returns : | action with reference count increased by one
|
void osso_abook_contact_field_action_unref (OssoABookContactFieldAction *action);
Releases a reference on action
. if the reference count reaches 0, action
will be freed
action : |
a OssoABookContactFieldAction |
OssoABookContactAction osso_abook_contact_field_action_get_action (OssoABookContactFieldAction *action);
Gets the action type for the specified action
action : |
a OssoABookContactFieldAction |
OssoABookContactField* osso_abook_contact_field_action_get_field (OssoABookContactFieldAction *action);
Gets the OssoABookContactField associated with action
action : |
a OssoABookContactFieldAction |
GtkWidget* osso_abook_contact_field_action_get_widget (OssoABookContactFieldAction *action);
Gets the GtkWidget associated with action
action : |
a OssoABookContactFieldAction |
McProfile* osso_abook_contact_field_action_get_profile (OssoABookContactFieldAction *action);
Gets the McProfile associated with action
action : |
a OssoABookContactFieldAction |
gboolean osso_abook_contact_field_action_is_basic (OssoABookContactFieldAction *action);
GtkWidget* osso_abook_contact_field_create_button (OssoABookContactField *field, const char *title, const char *icon_name);
Creates an action button for field
.
field : |
the OssoABookContactField |
title : |
title for this button, or NULL to use default title
|
icon_name : |
icon name for this button, or NULL to use default icon
|
Returns : | A new action button for this contact field. |
GtkWidget* osso_abook_contact_field_get_label_widget (OssoABookContactField *field);
Gets a widget to be used as a label for the specified field
. This widget is
not necessarily a GtkLabel. For example, the label widget for a phone
number field may be a button that allows you to choose different types of
phone types (e.g. home / work / mobile).
field : |
a OssoABookContactField |
Returns : | a label widget owned by field
|
GtkWidget* osso_abook_contact_field_get_editor_widget (OssoABookContactField *field);
gboolean osso_abook_contact_field_has_editor_widget (OssoABookContactField *field);
gboolean osso_abook_contact_field_is_readonly (OssoABookContactField *field);
Checks whether field
is read-only or writable
field : |
a OssoABookContactField |
Returns : | TRUE if field is read-only, else FALSE
|
gboolean osso_abook_contact_field_is_bound_im (OssoABookContactField *field);
This function returns whether the field refers to a bound IM username.
In other words, it returns TRUE
if the contact is stored on the roster on
the server, FALSE
if not (and thus the field is editable in the contact
editor). The term 'bound username' also implies that it has been normalized
by the server.
field : |
An OssoABookContactField |
Returns : | TRUE if the contact is bound, FALSE otherwise.
|
gboolean osso_abook_contact_field_is_modified (OssoABookContactField *field);
field : |
An OssoABookContactField |
Returns : | TRUE if the field has been modified locally, else FALSE
|
gboolean osso_abook_contact_field_is_empty (OssoABookContactField *field);
field : |
An OssoABookContactField |
Returns : | TRUE if the field is empty, else FALSE
|
gboolean osso_abook_contact_field_is_mandatory (OssoABookContactField *field);
Checks whether field
is required to exist for each contact. If a field is
mandatory, it cannot be removed and must be present in order to save a
contact.
field : |
An OssoABookContactField |
Returns : | TRUE if the field is mandatory, else FALSE
|
void osso_abook_contact_field_set_mandatory (OssoABookContactField *field, gboolean mandatory);
Marks field
as a mandatory field. See
osso_abook_contact_field_is_mandatory()
for more information about what this
means.
field : |
An OssoABookContactField |
gboolean osso_abook_contact_field_activate (OssoABookContactField *field);
Activates the editor widget for field
, if any. Generally this will display a
picker dialog so that the user can choose a new value for the field.
field : |
An OssoABookContactField |
Returns : | TRUE if the field has been modified, else FALSE
|
int osso_abook_contact_field_cmp (OssoABookContactField *a, OssoABookContactField *b);
Compares a
and b
according to sort order, grouping children together with
their parents.
a : |
First OssoABookContactField to compare |
b : |
Second OssoABookContactField to compare |
Returns : | 0 if fields are equal, -1 if a comes before b , +1 if b comes before
a
|
GList* osso_abook_contact_field_list_supported_fields (GHashTable *message_map, OssoABookContact *master_contact, OssoABookContactFieldPredicateaccept_field , gpointer user_data);
Iterates through all possible fields and calls accept_field
on them. If
accept_field
returns TRUE
, the field will be added to the list of supported
fields.
message_map : |
a map from generic ids to contextual ids (see
osso_abook_message_map_new() )
|
master_contact : |
the master contact associated with this field, if any |
accept_field : |
Function which determines whether field is accepted |
user_data : |
additional data passed to accept_field for each field
|
Returns : | List of supported fields. The list and its contents are owned by the caller. |
"attribute"
property"attribute" gpointer : Read / Write / Construct Only
The VCard attribute backing this field.
"display-title"
property"display-title" gchar* : Read
The message ID field labels.
Default value: NULL
"display-value"
property"display-value" gchar* : Read
A human friendly string represeting the attribute value.
Default value: NULL
"icon-name"
property"icon-name" gchar* : Read
The name of the icon to use with this field.
Default value: NULL
"master-contact"
property"master-contact" OssoABookContact* : Read / Write / Construct Only
The master contact if one is associated with this field.
"message-map"
property"message-map" GHashTable* : Read / Write
Mapping for generic message ids to context ids.
"modified"
property"modified" gboolean : Read
Check if the field has been modified.
Default value: FALSE
"roster-contact"
property"roster-contact" OssoABookContact* : Read / Write / Construct Only
The roster contact if one is associated with this field.