Rename additional header files to avoid conflicts with KDE4

1 files changed, 0 insertions, 372 deletions

diff --git a/kabc/HOWTO b/kabc/HOWTO
deleted file mode 100644
index 7b41371b0..000000000
--- a/kabc/HOWTO
+++ /dev/null
@@ -1,372 +0,0 @@
-The KDE Address Book Framework
-===============================
-
-The KDE address book framework tries to provide an easy to use and powerful
-mechanism to handle contacts in all KDE applications.
-
-If you want to make use of it, this small introduction to programming
-with libkabc may be helpful.
-
-
-General Concepts
-=================
-
-In libkabc the storage and management of contacts is devided in 2 layers.
-
-******************
-Management Layer *
-******************
-
-     .-------------------.
-     | KABC::AddressBook |
-    .--------------------------------.
-    | KABC::Addressee                |  => Iterators
-    | KABC::Addressee                |
-    | KABC::Addressee                |  => Search functions
-    | ...                            |
-    `--------------------------------'
-                       |
- - - - - - - - - - - - | - - - - - - - - - - - - -
-                       |
-***************        |
-Storage Layer *        |
-***************        |  .......................
-                       |  .                     . - Network
-  .---------------.    |  .  .---------------.  .
-  | ResourceFile  |----+-----| ResourceLDAP  |  .
-  `---------------'    |  .  `---------------'  .
-  .---------------.    |  .  .---------------.  .
-  | ResourceDir   |----+-----| ResourceNet   |  .
-  `---------------'       .  `---------------'  .
-                          .                     .
-                          .......................
-
-
-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
-and provides 2 kinds of access methods.
-1) Iterators
-    With iterators you can iterate over each of the contacts of the
-    address book and perform an action on it
-
-2) Search functions
-    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
-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 single backends.
-At the moment libkabc provides 4 types of resources:
-1) ResourceFile
-  - stores all contacts in a single file
-
-2) ResourceDir
-  - stores each contact in its own file with the unique identifier of the
-    contact as a filename, will all of the files together in one directory
-
-3) ResourceLDAP
-  - stores all of the contacts on a LDAP server
-
-4) ResourceNet
-  - stores all contacts in a single file, which can be accessable via HTTP,
-    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
-and perform a save action.
-
-Examples
-=========
-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
------------------------------------------
-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
-address book of the user automatically. You can use it the following way:
-
-
-     #include <kabc/stdaddressbook.h>
-
- 1:  KABC::AddressBook *ab = KABC::StdAddressBook::self();
- 2:  KABC::AddressBook::Iterator it;
- 3:  for ( it = ab->begin(); it != ab->end(); ++it ) {
- 4:    KABC::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).
-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.
-You could also use (*it).formattedName() directly. In line 6 the formatted name
-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
----------------------------------
-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.
-The following code will create a file resource and save a contact into it:
-
-
-     #include <kabc/addressbook.h>
-     #include <kabc/resourcefile.h>
-
- 1:  KABC::AddressBook ab;
- 2:
- 3:  // create a file resource
- 4:  KABC::Resource *res = new KABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" );
- 5:
- 6:  if ( !ab.addResource( res ) ) {
- 7:    kdDebug() << "Unable to open resource" << endl;
- 8:    return 1;
- 9:  }
-10:
-11:  if ( !ab.load() ) {
-12:    kdDebug() << "Unable to load address book!" << endl;
-13:    return 2;
-14:  }
-15:
-16:  KABC::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
-24:  addr.setTimeZone( tz );
-25:
-26:  // GEO
-27:  KABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument
-28:  addr.setGeo( geo );
-29:
-30:  addr.setTitle( "dude, the" );
-31:  addr.setRole( "developer" );
-32:  addr.setOrganization( "KDE e.V." );
-33:  addr.setNote( "Yet another senseless note..." );
-34:  addr.setUrl( KURL( "http://kaddressbook.org" ) );
-35:
-36:  // CLASS
-37:  KABC::Secrecy secrecy( KABC::Secrecy::Confidential );
-38:  addr.setSecrecy( secrecy );
-39:
-40:  // PHOTO or LOGO
-41:  KABC::Picture photo;
-42:  QImage img;
-43:  if ( img.load( "face.png", "PNG" ) ) {
-44:    photo.setData( img );
-45:    photo.setType( "image/png" );
-46:    addr.setPhoto( photo );
-47:  }
-48:
-49:  addr.insertEmail( "otto@kde.se", true );  // preferred email
-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 );
-55:  addr.insertPhoneNumber( phoneHome );
-56:  addr.insertPhoneNumber( phoneWork );
-57:
-58:  // ADR
-59:  KABC::Address homeAddr( KABC::Address::Home );
-60:  homeAddr.setStreet( "Milliwaystreet 42" );
-61:  homeAddr.setLocality( "London" );
-62:  homeAddr.setRegion( "Saxony" );
-63:  homeAddr.setPostalCode( "43435" );
-64:  homeAddr.setCountry( "Germany" );
-65:  addr.insertAddress( homeAddr );
-66:
-67:  addr.insertCategory( "LUG-Dresden-Members" );
-68:
-69:  addr.insertCustom( "KADDRESSBOOK", "X-Anniversary", "21.04.2009" );
-70:
-71:  ab.insertAddressee( addr ); // will be assigned to the standard resource
-72:                              // automatically
-73:
-74:  KABC::Ticket *ticket = ab.requestSaveTicket( res );
-75:  if ( !ticket ) {
-76:    kdError() << "Resource is locked by other application!" << endl;
-77:  } else {
-78:    if ( !ab.save( ticket ) ) {
-79:      kdError() << "Saving failed!" << endl;
-80:      ab.releaseSaveTicket( ticket );
-81:    }
-82:
-83:  }
-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).
-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
-2) Binary, which increases performance during loading and saving
-
-In line 6 we try to plug the resource into the addressbook. The addressbook
-class tries to open the resource immediately and returns whether opening was
-successful. We add here only one resource, but you can add as many resources
-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.
-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.
-You can set these values manually as well by calling
-  addr.setGivenName( "Otto" );
-and
-  addr.setFamilyName( "Meyer" );
-etc. etc.
-
-In line 23 we use the class KABC::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
-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
-as argument.
-
-In line 41 we make use of KABC::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.
-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
-string representation as first argument and the type as second. The types can
-be combined, so 'KABC::PhoneNumber::Home | KABC::PhoneNumber::Fax' would be
-the Home Fax.
-
-In line 59 we create a KABC::Address object and set the single parts in the
-following lines.
-
-In line 67 we assign the contact to a special category.
-
-A contact can also contain custom entries, which are not specified in the API,
-so you can add custom values with insertCustom() as shown in line 69.
-The first argument of this function should be the name of the application, so
-2 applications which use the same custom entry accidentally, do not overwrite
-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
-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 );
-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* )
-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
-returns whether saving succeeded.  It also releases the save ticket when successful.
-
-Important!
-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
-please take a look at the official API documentation or the header files.
-
-
-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
-track of all available distribution lists and the latter one is the
-representation of one list.
-
-
-     #include <kabc/distributionlist.h>
-     #include <kabc/stdaddressbook.h>
-
- 1:  KABC::DistributionListManager manager( KABC::StdAddressBook::self() );
- 2:
- 3:  // load the lists
- 4:  manager.load();
- 5:
- 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 );
-10:    kdDebug() << list->name() << endl;
-11:
-12:    QStringList emails = list->emails();
-13:    QStringList::Iterator eit;
-14:    for ( eit = emails.begin(); eit != emails.end(); ++eit )
-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
-currently available email addresses.
-In line 4 the manager loads all distribution lists from the central config file
-$HOME/.trinity/share/apps/kabc/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
-following actions on it:
- - set / get the name
- - insert an entry
- - remove an entry
- - get a list of all email addresses
- - get a list of all entries (which includes the uids)
-
-In line 12 we query all email addresses of every resource and print them out.
-
-<kabc/distributionlist.h> contains also the declaration for the class
-KABC::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 <kabc/distributionlist.h>
-
- 1:  connect( KABC::DistributionListWatcher::self(), SIGNAL( changed() ),
- 2:           this, SLOT( slotDistributionListChanged() ) );
-
-You see, as usual, easy ;)
-