diff options
Diffstat (limited to 'tdeabc/HOWTO')
| -rw-r--r-- | tdeabc/HOWTO | 116 |
1 files changed, 58 insertions, 58 deletions
diff --git a/tdeabc/HOWTO b/tdeabc/HOWTO index 3941b2033..5187f2580 100644 --- a/tdeabc/HOWTO +++ b/tdeabc/HOWTO @@ -18,11 +18,11 @@ Management Layer * ****************** .-------------------. - | KABC::AddressBook | + | TDEABC::AddressBook | .--------------------------------. - | KABC::Addressee | => Iterators - | KABC::Addressee | - | KABC::Addressee | => Search functions + | TDEABC::Addressee | => Iterators + | TDEABC::Addressee | + | TDEABC::Addressee | => Search functions | ... | `--------------------------------' | @@ -44,8 +44,8 @@ Storage Layer * | The Management Layer --------------------- -The Management Layer consists of the two classes KABC::AddressBook and -KABC::Addressee. KABC::AddressBook is a container for KABC::Addressee objects +The Management Layer consists of the two classes TDEABC::AddressBook and +TDEABC::Addressee. TDEABC::AddressBook is a container for TDEABC::Addressee objects and provides 2 kinds of access methods. 1) Iterators With iterators you can iterate over each of the contacts of the @@ -55,13 +55,13 @@ and provides 2 kinds of access methods. With search functions you can search for contacts with special attributes such as "all contacts with the name 'Harald'" -The class KABC::Addressee represents a single contact and contains all data +The class TDEABC::Addressee represents a single contact and contains all data a vCard could store (as specified in RFC 2426). The Storage Layer ------------------ -The Storage Layer consists of the class KABC::Resource and its derived classes. -These classes are used by KABC::AddressBook to load and store the contacts to +The Storage Layer consists of the class TDEABC::Resource and its derived classes. +These classes are used by TDEABC::AddressBook to load and store the contacts to the single backends. At the moment libkabc provides 4 types of resources: 1) ResourceFile @@ -79,7 +79,7 @@ At the moment libkabc provides 4 types of resources: FTP, Fish, WebDAV, POP3, IMAP or whatever the KIO frame work supports In general the developer does not have to take how to save the single contacts. -He just has to plug one of the above mentioned resources into KABC::AddressBook +He just has to plug one of the above mentioned resources into TDEABC::AddressBook and perform a save action. Examples @@ -88,27 +88,27 @@ Like a picture, C/C++ code is worth a 1000 words I'd like to give you a lot of examples now, how to use libkabc for several tasks: -Using KABC::StdAddressBook and Iterators +Using TDEABC::StdAddressBook and Iterators ----------------------------------------- Normally you have to plugin the resources manually into the addressbook object and call the load() function before you can access the contacts, but there is -a special class KABC::StdAddressBook, which loads all resources of the standard +a special class TDEABC::StdAddressBook, which loads all resources of the standard address book of the user automatically. You can use it the following way: #include <tdeabc/stdaddressbook.h> - 1: KABC::AddressBook *ab = KABC::StdAddressBook::self(); - 2: KABC::AddressBook::Iterator it; + 1: TDEABC::AddressBook *ab = TDEABC::StdAddressBook::self(); + 2: TDEABC::AddressBook::Iterator it; 3: for ( it = ab->begin(); it != ab->end(); ++it ) { - 4: KABC::Addressee addr = (*it); + 4: TDEABC::Addressee addr = (*it); 5: 6: kdDebug() << "Name = " << addr.formattedName() << endl; 7: } The above example prints out the names of all the contacts in the user's address book. In line 1 you retrieve a pointer to the user's standard address book -(provided by KABC::StdAddressBook via a singleton design pattern). +(provided by TDEABC::StdAddressBook via a singleton design pattern). In line 2 an iterator is defined, which is used in line 3 to iterate over the whole address book. The assignment in line 4 is intended only to show more clearly how iterators function. @@ -117,21 +117,21 @@ of the current contact is printed out to stderr. As you can see that's all magic, and it's quite easy ;) -Using KABC::AddressBook manually +Using TDEABC::AddressBook manually --------------------------------- In some cases you don't want to load the user's standard address book, but, for example, just a single vCard. For this purpose you have to use the -class KABC::AddressBook and handle the resource stuff manually. +class TDEABC::AddressBook and handle the resource stuff manually. The following code will create a file resource and save a contact into it: #include <tdeabc/addressbook.h> #include <tdeabc/resourcefile.h> - 1: KABC::AddressBook ab; + 1: TDEABC::AddressBook ab; 2: 3: // create a file resource - 4: KABC::Resource *res = new KABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" ); + 4: TDEABC::Resource *res = new TDEABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" ); 5: 6: if ( !ab.addResource( res ) ) { 7: kdDebug() << "Unable to open resource" << endl; @@ -143,18 +143,18 @@ The following code will create a file resource and save a contact into it: 13: return 2; 14: } 15: -16: KABC::Addressee addr; +16: TDEABC::Addressee addr; 17: addr.setNameFromString( "Otto Harald Meyer" ); 18: addr.setBirthday( QDate( 1982, 07, 19 ) ); 19: addr.setNickName( "otto" ); 20: addr.setMailer( "kmail" ); 21: 22: // TZ -23: KABC::TimeZone tz( 60 ); // takes time shift in minutes as argument +23: TDEABC::TimeZone tz( 60 ); // takes time shift in minutes as argument 24: addr.setTimeZone( tz ); 25: 26: // GEO -27: KABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument +27: TDEABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument 28: addr.setGeo( geo ); 29: 30: addr.setTitle( "dude, the" ); @@ -164,11 +164,11 @@ The following code will create a file resource and save a contact into it: 34: addr.setUrl( KURL( "http://kaddressbook.org" ) ); 35: 36: // CLASS -37: KABC::Secrecy secrecy( KABC::Secrecy::Confidential ); +37: TDEABC::Secrecy secrecy( TDEABC::Secrecy::Confidential ); 38: addr.setSecrecy( secrecy ); 39: 40: // PHOTO or LOGO -41: KABC::Picture photo; +41: TDEABC::Picture photo; 42: QImage img; 43: if ( img.load( "face.png", "PNG" ) ) { 44: photo.setData( img ); @@ -180,13 +180,13 @@ The following code will create a file resource and save a contact into it: 50: addr.insertEmail( "otti@yahoo.com", false ); 51: 52: // TEL -53: KABC::PhoneNumber phoneHome( "0351 5466738", KABC::PhoneNumber::Home ); -54: KABC::PhoneNumber phoneWork( "0351 2335411", KABC::PhoneNumber::Work ); +53: TDEABC::PhoneNumber phoneHome( "0351 5466738", TDEABC::PhoneNumber::Home ); +54: TDEABC::PhoneNumber phoneWork( "0351 2335411", TDEABC::PhoneNumber::Work ); 55: addr.insertPhoneNumber( phoneHome ); 56: addr.insertPhoneNumber( phoneWork ); 57: 58: // ADR -59: KABC::Address homeAddr( KABC::Address::Home ); +59: TDEABC::Address homeAddr( TDEABC::Address::Home ); 60: homeAddr.setStreet( "Milliwaystreet 42" ); 61: homeAddr.setLocality( "London" ); 62: homeAddr.setRegion( "Saxony" ); @@ -201,7 +201,7 @@ The following code will create a file resource and save a contact into it: 71: ab.insertAddressee( addr ); // will be assigned to the standard resource 72: // automatically 73: -74: KABC::Ticket *ticket = ab.requestSaveTicket( res ); +74: TDEABC::Ticket *ticket = ab.requestSaveTicket( res ); 75: if ( !ticket ) { 76: kdError() << "Resource is locked by other application!" << endl; 77: } else { @@ -214,8 +214,8 @@ The following code will create a file resource and save a contact into it: 84: 85: return 0; -In line 1 the KABC::AddressBook is created. In line 4 you creat the -KABC::ResourceFile (which will handle the loading/saving). +In line 1 the TDEABC::AddressBook is created. In line 4 you creat the +TDEABC::ResourceFile (which will handle the loading/saving). The resource takes 2 arguments, the first is the file name and the second one the file format. At the moment libkabc supports two file formats: 1) vCard, as specified in RFC 2426 @@ -229,8 +229,8 @@ as you want. In line 11 we try to load all contacts from the backends into the address book. As before, it returns whether opening was successful. -In line 16 a KABC::Addressee is created, which we will fill now with data, -before inserting it into the KABC::AddressBook. +In line 16 a TDEABC::Addressee is created, which we will fill now with data, +before inserting it into the TDEABC::AddressBook. The setNameFromString() function in the following line takes a string as argument and tries to parse it into the single name components such as: given name, family name, additional names, honoric prefix and honoric suffix. @@ -240,34 +240,34 @@ and addr.setFamilyName( "Meyer" ); etc. etc. -In line 23 we use the class KABC::TimeZone to store the timezone. This class +In line 23 we use the class TDEABC::TimeZone to store the timezone. This class takes the time shift in minutes. -In line 27 the KABC::Geo class is used for storing the geographical +In line 27 the TDEABC::Geo class is used for storing the geographical information. The arguments are the latitude and longitude as float values. -KABC::Secrecy in line 37 represents the CLASS entity of a vCard and can take -KABC::Secrecy::Public, KABC::Secrecy::Private or KABC::Secrecy::Confidential +TDEABC::Secrecy in line 37 represents the CLASS entity of a vCard and can take +TDEABC::Secrecy::Public, TDEABC::Secrecy::Private or TDEABC::Secrecy::Confidential as argument. -In line 41 we make use of KABC::Picture class to store the photo of the +In line 41 we make use of TDEABC::Picture class to store the photo of the contact. This class can contain either an URL or the raw image data in form of a QImage, in this example we use the latter. In line 43 we try to load the image "face.png" from the local directory and -assign this QImage to the KABC::Picture class via the setData() function. +assign this QImage to the TDEABC::Picture class via the setData() function. Additionally we set the type of the picture to "image/png". From 49 - 50 we insert 2 email addresses with the first one as preferred (second argument is true). In 53 and the following 3 lines we add two telephone numbers. For this purpose -libkabc provides the KABC::PhoneNumber class, which takes the phone number in +libkabc provides the TDEABC::PhoneNumber class, which takes the phone number in string representation as first argument and the type as second. The types can -be combined, so 'KABC::PhoneNumber::Home | KABC::PhoneNumber::Fax' would be +be combined, so 'TDEABC::PhoneNumber::Home | TDEABC::PhoneNumber::Fax' would be the Home Fax. -In line 59 we create a KABC::Address object and set the single parts in the +In line 59 we create a TDEABC::Address object and set the single parts in the following lines. In line 67 we assign the contact to a special category. @@ -279,25 +279,25 @@ The first argument of this function should be the name of the application, so the data for each other. The second argument contains the name of the custom entry and the third argument the value in string representation. -In line 71 we finally insert the KABC::Addressee object into the -KABC::AddressBook. Since we have only one resource loaded, the contact is +In line 71 we finally insert the TDEABC::Addressee object into the +TDEABC::AddressBook. Since we have only one resource loaded, the contact is automatically assigned to this resource. If you have several writeable resources loaded, you should ask the user which resource the contact shall belong to and assign the selected resource to the contact with - KABC::Addressee.setResource( KABC::Resource *resource ); + TDEABC::Addressee.setResource( TDEABC::Resource *resource ); before inserting it into the address book. To prevent multiple access to one resource and possible resulting data loss we have to lock the resource before saving our changes. -For this purpose KABC::AddressBook provides the function - requestSaveTicket( KABC::Resource* ) +For this purpose TDEABC::AddressBook provides the function + requestSaveTicket( TDEABC::Resource* ) which takes a pointer to the resource which shall be saved as argument and returns a so called 'Save Ticket' if locking succeeded or a null pointer if the resource is already locked by another application. So when we retrieved a valid ticket in line 74, we try to save our changes in line 78. -The KABC::AddressBook::save() function takes the save ticket as argument and +The TDEABC::AddressBook::save() function takes the save ticket as argument and returns whether saving succeeded. It also releases the save ticket when successful. Important! @@ -305,8 +305,8 @@ If the save() call fails, you have to release the save ticket manually, as is done in line 80, otherwise possible locks, created by the resources, won't be removed. -You can see also, that manual use is quite easy for the KABC::AddressBook class -and for the ResourceFile. For more information about the API of KABC::Addressee +You can see also, that manual use is quite easy for the TDEABC::AddressBook class +and for the ResourceFile. For more information about the API of TDEABC::Addressee please take a look at the official API documentation or the header files. @@ -315,7 +315,7 @@ Distribution Lists libkabc provides so called distribution lists to group contacts. These lists just store the uid of contacts, so they can be used for every kind of contact grouping. There are 2 classes which handle the whole distribution list tasks, -KABC::DistributionListManager and KABC::DistributionList. The first one keeps +TDEABC::DistributionListManager and TDEABC::DistributionList. The first one keeps track of all available distribution lists and the latter one is the representation of one list. @@ -323,7 +323,7 @@ representation of one list. #include <tdeabc/distributionlist.h> #include <tdeabc/stdaddressbook.h> - 1: KABC::DistributionListManager manager( KABC::StdAddressBook::self() ); + 1: TDEABC::DistributionListManager manager( TDEABC::StdAddressBook::self() ); 2: 3: // load the lists 4: manager.load(); @@ -331,7 +331,7 @@ representation of one list. 6: QStringList listNames = manager.listNames(); 7: QStringList::Iterator it; 8: for ( it = listNames.begin(); it != listNames.end(); ++it ) { - 9: KABC::DistributionList *list = manager.list( *it ); + 9: TDEABC::DistributionList *list = manager.list( *it ); 10: kdDebug() << list->name() << endl; 11: 12: QStringList emails = list->emails(); @@ -340,14 +340,14 @@ representation of one list. 15: kdDebug() << QString( "\t%1" ).arg( (*eit).latin1() ) << endl; 16: } -In the first line a KABC::DistributionListManager is created. The manager takes -a pointer to a KABC::AddressBook, because he has to resolve the stored uids to +In the first line a TDEABC::DistributionListManager is created. The manager takes +a pointer to a TDEABC::AddressBook, because he has to resolve the stored uids to currently available email addresses. In line 4 the manager loads all distribution lists from the central config file $HOME/.trinity/share/apps/tdeabc/distlists. The next line queries the names of all available distribution lists, which are used in line 9 to retrieve a pointer to the specific list. -Now that you have a KABC::DistributionList object, you can performe the +Now that you have a TDEABC::DistributionList object, you can performe the following actions on it: - set / get the name - insert an entry @@ -358,14 +358,14 @@ following actions on it: In line 12 we query all email addresses of every resource and print them out. <tdeabc/distributionlist.h> contains also the declaration for the class -KABC::DistributionListWatcher. This class exists only once per application and +TDEABC::DistributionListWatcher. This class exists only once per application and its only job is to emit a signal as soon as the distribution list file has changed. So to make your application aware of changes use the following code: #include <tdeabc/distributionlist.h> - 1: connect( KABC::DistributionListWatcher::self(), SIGNAL( changed() ), + 1: connect( TDEABC::DistributionListWatcher::self(), SIGNAL( changed() ), 2: this, SLOT( slotDistributionListChanged() ) ); You see, as usual, easy ;) |