[Tcladdressbook-commits] Help TclAddressBookHelp.aida,NONE,1.1

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/tcladdressbook/Help
In directory sc8-pr-cvs1:/tmp/cvs-serv6562/Help

Added Files:
	TclAddressBookHelp.aida 
Log Message:
Base file for doc written in AIDA. First checkin.

--- NEW FILE: TclAddressBookHelp.aida ---
:Title:			Tcladdressbook Help
:Project:		addressbook extension for Tcl
:Version:		$Revision: 1.1 $
:CVSDate:		$Date: 2003/12/09 08:05:00 $
:Author:		Bernard Desgraupes <bde...@ea...>
:Homepage:		<http://webperso.easyconnect.fr/bdesgraupes/>
:Created: 		2003-11-26 14:30:03
:Modified:	 	2003-12-08 08:21:01
:Keywords:		Address book, data base

((/
This is a manual page for the Tcladdressbook extension for Tcl.
/))
((toc

((np

((s1 NAME
addressbook - manipulate the Macintosh OSX Address Book database

((s1 SYNOPSIS
((|
(| package require addressbook
(| addressbook subcommand ?arg arg ...?
|))

((s1 INTRODUCTION

The argument ((i subcommand i)) indicates what operation  to  perform.  Any
unique abbreviation for each subcommand   is    acceptable.    The    valid
subcommands are explained in the next sections.

((s1 SUBCOMMANDS

((s4 addressbook changed
This command returns 1 if there has been changes made to the database, 0 
otherwise. Changes are made in memory with commands such as ((b addressbook value b)), 
((b addressbook create b)), ((b addressbook remove b)). To make these changes permanent, 
one must call the ((b addressbook save b)) command.

((s4 addressbook count
!! ((s4 addressbook count (-groups | -persons)
This command returns the count of existing groups or persons in the 
database. 
!! One can specify a particular group with the -ingroup option 
!! to count only the subgroups or members of this group.

((s4 addressbook create (group | person) ((i name i)) ?-ingroup ((i groupID i))?
This command lets you create a new group or a new person record. The ((i name i)) 
argument is the name to give to the new group or the last name of the 
person for which a new record is created. With the ((i -ingroup i)) option one can 
make the newly created record a subgroup or a member of the particular 
group with unique ID ((i groupID i)). If no error occurs, the command returns 
the unique ID of the created record. 

((s4 addressbook export ((i personID i))
This command lets you export the record with unique ID 
((i personID i)) as a VCard. The result should be 
considered as binary data since it can contain an image associated to the 
record. 

((s4 addressbook getme ((i arrayvar i))
This command retrieves all the data available in the database concerning the logged-in user 
("Me") and stores it in the array variable specified by the ((i arrayvar i)) 
argument. See the ((b addressbook record b)) 
command for a description of the format of the various kinds of 
properties.

((s4 addressbook groups ?-ids? ?-ingroup ((i groupID i))?
This command returns a list of all the existing group records: if no option is 
specified, it is a list whose elements are sublists made of two 
elements. The first element is the unique ID associated with the group and 
the second is its name. If the ((i -ids i)) argument is specified, the returned 
list will contain only the unique IDs of the groups. If the ((i -ingroup i)) 
option is specified, only the subgroups contained in the group 
with ID ((i groupID i)) will be returned.

((s4 addressbook image ((i personID i)) ?((i imageData i))?
If no ((i imageData i)) argument is specified, this command 
returns the custom image associated with the record 
corresponding to the unique ID ((i personID i)). The returned bytes 
are binary data. If no image exists, it raises an error. If 
an ((i imageData i)) argument is specified, it should contain valid binary data 
defining an image which will be associated the record with unique ID ((i personID i)).

((s4 addressbook import ((i vCardData i))
This command imports data in VCard format. The data specified by 
the ((i vCardData i)) argument must be valid data in VCard format: 
a new record is created in the database corresponding to the information 
contained in the VCard. Note that the data can be binary if the VCard contains an 
image.

((s4 addressbook parents ?-ids? ((i recordID i))
This command returns a list of all the groups the record with unique ID  
((i recordID i)) belongs to. The elements of this list are sublists made 
of one or two items: the unique ID and, possibly, the name of the record 
if this field exists. If the ((i -ids i)) option is specified, only IDs are 
returned.

((s4 addressbook persons ?-ids? ?-ingroup ((i groupID i))?
This command returns a list of all the existing person records: if no
option is specified, it is a list whose elements are sublists made of one
or two items: the unique ID and, possibly, the name of the record if this
field exists. If the ((i -ids i)) argument is specified, the
returned list will contain only the unique IDs. If the
((i -ingroup i)) option is specified, only the members belonging to the group
with ID ((i groupID i)) will be returned.

((s4 addressbook property names (-groups | -persons)
This command returns a list of all the properties defined in the database 
for group or person records. New properties can be created or removed with 
the ((b addressbook property add b)) and ((b addressbook property remove b)) commands.

((s4 addressbook property add (-groups | -persons) ((i propName i)) ((i propType i))
This command lets you add a new property to the database, either for 
person or for group records. The name of the new property is specified by 
the ((i propName i)) argument: it must be unique. One can get the list of 
all the existing properties with the ((b addressbook property names b)) command. 
The type of the property is specified by 
the ((i propType i)) argument. This argument can have one of the following values:
((i Array, Data, Date, Dictionary, Integer, Real, String, MultiArray,
MultiData, MultiDate, MultiDictionary, MultiInteger, MultiReal, MultiString. i))

((s4 addressbook property remove (-groups | -persons) ((i propName i))
This command lets you remove a property from the database, either for 
person or for group records. The name of the property is specified in the  
((i propName i)) argument. One can get the list of all 
the existing properties with the ((b addressbook property names b)) command. 

((s4 addressbook record ((i recordID arrayvar i))
This command retrieves all the data available in the database concerning
the record with unique ID ((i recordID i)) and stores it in the array
variable specified by the ((i arrayvar i)) argument.  The keys of the array
(as returned by the ((b array names b)) Tcl command) are the names of the
properties: the values are the current values of the corresponding
property.  Only existing properties for the specified record are returned
by this command: you should unset the ((i arrayvar i)) variable before
invoking ((b addressbook record b)) in case you use this command repeatedly
in order to be sure it does not keep stale information.
((nl The format used to return a particular value depends on the type of 
the property (string, integer, date, multivalue etc.). Some properties have 
a multiple type: MultiString for fields like Email, Phone etc., MultiDate 
for fields like ABDate, MultiDictionary for the Address field. In case of a 
multivalue, the returned value is a Tcl list. Each element of the list 
corresponds to a single property. For instance:
((lu
((li the elements of a MultiString or MultiDate value list are two-elements 
sublists: the first element is the label of the corresponding 
property (like Home, Work etc.) and the second is the value itself.
((li the elements of a MultiDictionary value list are lists themselves,
representing a Label/Dictionary pair (dictionary in the AddressBook sense, not a Tcl
dictionary as defined in version 8.5 of Tcl).  Each element of this list
has two elements: the first one is the label describing the address (like
Home, Work etc.)  and the second one is a list representing the dictionary.
The lists representing dictionaries contain two-elements sublists: the
first item is the key in the dictionary and the second one is the value
associated with this key.  For instance a person could have two addresses:
each address will be returned as a Label/Dictionary pair; the
elements of the dictionary are pairs like {City Paris} or {CountryCode fr}.
lu))
((nl Dates are returned as values suitable for use with the ((b clock format b)) 
Tcl command. It is the number of seconds relative to "Thu Jan 01 00:00:00 
CET 1970".

((s4 addressbook remove ((i recordID i)) ?-fromgroup ((i groupID i))?
This command removes the record with unique ID ((i recordID i)) from the
database or from a particular subgroup specified by its unique ID with the
((i -fromgroup i)) option.  Note that any changes made to the database
won't be definitive until you invoke the ((b addressbook save b)) command.

((s4 addressbook save
This command lets you save the changes made in the database. Commands such 
as ((b addressbook value b)), ((b addressbook create b)) or ((b addressbook 
remove b)) modify the data in memory: to make the changes definitive in the 
database, one must call explicitely the ((b addressbook save b)) command. 
To check whether there has been changes in the database, use the 
((b addressbook changed b)) command.

((s4 addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? ((i property op value i))
This command returns all the records corresponding to the criterion 
described by the last three arguments:
((lu
((li ((i property i)) is the name of the property whose value will be 
compared to the  ((i value i)) argument
((li ((i op i)) is an operator specifying the type of comparison. It can be 
one of the following symbols: 
((|
	==, !=, <, <=, >, >=
|))
((li ((i value i)) is the value property you are searching
lu))
((nl The ((i -groups i)) or ((i -persons i)) arguments let you specify the kind of records 
you want to search. If it is not specified, the default is ((i -person i)).
If the ((i -ids i)) option is specified, only IDs of the matching records are 
returned, rather than pairs made of the ID and the name. The ((i -nocase i)) 
argument concerns string comparisons and requires that no distinction be 
made between uppercase and lowercase letters.

((s4 addressbook type ((i recordID i))
This command returns the type (ABPerson or ABGroup) of the record with 
unique ID ((i recordID i)).

((s4 addressbook value ((i recordID propertyName i)) ?((i value i))?
This command lets you get or set the value of a particular property for 
the record with unique ID ((i recordID i)). If the ((i value i)) argument is not 
specified, it returns the current value of the property specified in the 
((i propertyName i)) argument. If ((i value i)) is specified, the property 
((i propertyName i)) will be set to this value. See the ((b addressbook record b)) 
command for a description of the format used for the various kinds of 
properties.

((s1 INSTALLATION
The extension  is  made  of  two  files:  the  dynamic  library  (called
addressbook1.0.dylib in version 1.0) and a file pkgIndex.tcl necessary  for
Tcl to be able to  locate  the  extension  upon  request.  Both  files  are
contained in a folder called, in version 1.0, TclAddressBook1.0. This folder
should be installed on your system in /Library/Tcl or in ~/Library/Tcl or,
more generally, in any folder contained in your ((b auto_path b)) Tcl variable. If
you use the extension within the AlphaX editor (version 8.0b11 or greater),
you can also install it in the ((i Tclextensions i)) folder which is located at the
same level as the application.

((s1 VERSION HISTORY
((lu
((li 1.0 -  
lu))

((s1 REQUIREMENTS AND PORTABILITY
This extension is only useful  on  Macintosh  platforms.  Version  10.2  or
greater of the system is required: the AddressBook framework was introduced
in version 10.2 of the System (aka Jaguar).

((s1 KNOW ISSUES
Please e-mail any bug or problem you encounter: 
<bde...@us...>

((s1 LICENSE AND DISCLAIMER
This software is free software and distributed under the same licensing terms 
as the Tcl language itself. See license.terms in the Tcl distribution.

((|
   © Copyright Bernard Desgraupes 2003
|))

((s1 SOURCE CODE
Tcladdressbook is an Open Source Project. Its source code is public and can 
be found on the SourceForge site at the following address:
<http://sourceforge.net/projects/tcladdressbook>

((nl Tcladdressbook binary releases are available at
<http://sourceforge.net/project/showfiles.php?group_id=96169> or on my web 
page at <http://webperso.easyconnect.fr/bdesgraupes/tcl.html>

((nl The code is under CVS control. You can retrieve the latest stage of 
development using any CVS client. See instructions at:
<http://sourceforge.net/cvs/?group_id=96169>

((nl You can also browse the cvs repository online at
<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook> 

((s1 SEE ALSO
The Mk4Tcl extension.

((s1 KEYWORDS
Address book, data base