Development/Architecture/KDE3/Standard Resources: Difference between revisions

    From KDE TechBase
    (initial port of http://developer.kde.org/documentation/library/kdeqt/kde3arch/resources.html)
     
    (Marked this version for translation)
    (10 intermediate revisions by 7 users not shown)
    Line 1: Line 1:
    <languages />
    <translate>
    <!--T:1-->
    '''KDE Architecture - Accessing Standard Resource Directories'''
    '''KDE Architecture - Accessing Standard Resource Directories'''


    == Overview ==
    == Overview == <!--T:2-->


    <!--T:3-->
    KDE offers several ways to access the files that your application
    KDE offers several ways to access the files that your application
    installed on your user's hard disc while making it transparent
    installed on your user's hard disc while making it transparent
    Line 12: Line 17:
    expect ''man'' to lookup man pages in <tt>PATH</tt>.
    expect ''man'' to lookup man pages in <tt>PATH</tt>.


    <!--T:4-->
    Similiar to that concept KDE seperates search paths for different
    Similiar to that concept KDE seperates search paths for different
    things to make it simpler to add paths for a specific resource without
    things to make it simpler to add paths for a specific resource without
    Line 17: Line 23:
    requiring you to put everything into one directory.
    requiring you to put everything into one directory.


    <!--T:5-->
    The types of resources KDE offers are
    The types of resources KDE offers are


    <!--T:6-->
    * apps - applications menu (.desktop files)
    * apps - applications menu (.desktop files)
    * cgi - CGIs to run from khelpcenter
    * cgi - CGIs to run from khelpcenter</translate><translate>
    <!--T:7-->
    * config - configuration files
    * config - configuration files
    * data - where applications store data
    * data - where applications store data</translate><translate>
    <!--T:8-->
    * exe - executables installed privatly for KDE's use
    * exe - executables installed privatly for KDE's use
    * html - HTML documentation
    * html - HTML documentation</translate><translate>
    <!--T:9-->
    * icon - application icons to appear in the window manager or the panel
    * icon - application icons to appear in the window manager or the panel
    * lib - libraries and to be dlopened modules
    * lib - libraries and to be dlopened modules</translate><translate>
    <!--T:10-->
    * locale - translation files for KLocale
    * locale - translation files for KLocale
    * mime - mime types
    * mime - mime types</translate><translate>
    <!--T:11-->
    * sound - application sounds
    * sound - application sounds
    * toolbar - toolbar pictures
    * toolbar - toolbar pictures
    * wallpaper - wallpapers
    * wallpaper - wallpapers


    <!--T:12-->
    For all of them exist also Makefile aliases that configures created by the development
    For all of them exist also Makefile aliases that configures created by the development
    tools provided for KDE (e.g. kdevelop) will know about.
    tools provided for KDE (e.g. kdevelop) will know about.


    == KStandardDirs ==
    == KStandardDirs == <!--T:13-->


    <!--T:14-->
    This is one of the most central classes in kdelibs as
    This is one of the most central classes in kdelibs as
    it provides a basic service: it knows where the files
    it provides a basic service: it knows where the files
    reside on the user's harddisc. And it's meant to be the
    reside on the user's harddisk. And it's meant to be the
    only one that knows - to make the real location as
    only one that knows - to make the real location as
    transparent as possible to both the user and the applications.
    transparent as possible to both the user and the applications.


    <!--T:15-->
    For this it encapsulates all informations from the application
    For this it encapsulates all informations from the application
    and applications always refer to a file with a resource type
    and applications always refer to a file with a resource type
    (e.g. apps) and a filename (e.g. Home.desktop). In an ideal world
    (e.g. apps) and a filename (e.g. {{path|Home.desktop}}). In an ideal world
    the application would make no assumption where this file is and
    the application would make no assumption where this file is and
    leaves it up to <tt>KStandardDirs::findResource("apps", "Home.desktop")</tt>
    leaves it up to <tt>KStandardDirs::findResource("apps", "Home.desktop")</tt>
    to apply this knowledge.
    to apply this knowledge.


    The main idea behind KStandardDirs is that there are several
    <!--T:16-->
    The main idea behind {{class|KStandardDirs}} is that there are several
    toplevel prefixes where files are below. One of this prefixes is
    toplevel prefixes where files are below. One of this prefixes is
    the one where the user installed kdelibs into, one where the
    the one where the user installed kdelibs into, one where the
    Line 60: Line 77:
    {{path|share/apps/&lt;appname&gt;/pics}}.
    {{path|share/apps/&lt;appname&gt;/pics}}.


    <!--T:17-->
    So the search algorithm basicly appends to each prefix each registered
    So the search algorithm basicly appends to each prefix each registered
    suffix and tries to locate the file there.
    suffix and tries to locate the file there.
    Line 68: Line 86:
    example for icons.
    example for icons.


    === On the usage of <tt>locate</tt> and <tt>locateLocal</tt> ===
    === On the usage of <tt>locate</tt> and <tt>locateLocal</tt> === <!--T:18-->


    <!--T:19-->
    locate and locateLocal are both convenient functions that make the use of
    locate and locateLocal are both convenient functions that make the use of
    KStandardDirs as simple as possible. You have however the possibility to
    KStandardDirs as simple as possible. You have however the possibility to
    use the full power of KStandardDirs without them.
    use the full power of KStandardDirs without them.


    <!--T:20-->
    Typical KDE applications use resource files in one out of three ways:
    Typical KDE applications use resource files in one out of three ways:


    <!--T:21-->
    * A resource file is read but is never written. A system default is supplied but the user can override this default in his local .kde directory:
    * A resource file is read but is never written. A system default is supplied but the user can override this default in his local .kde directory:


    // Code example
    <!--T:22-->
    myFile = locate("appdata", "groups.lst")
    <syntaxhighlight lang="cpp-qt">
    myData = myReadGroups(myFile);
    // Code example
    myFile = locate("appdata", "groups.lst")
    myData = myReadGroups(myFile);
    </syntaxhighlight>


    <!--T:23-->
    * A resource file is read and written. If the user has no local version of the file the system default is used. The resource file is always written to the users local .kde directory.
    * A resource file is read and written. If the user has no local version of the file the system default is used. The resource file is always written to the users local .kde directory.


    // Code example
    <!--T:24-->
    myFile = locate("appdata", "groups.lst")
    <syntaxhighlight lang="cpp-qt">
    myData = myReadGroups(myFile);
    // Code example
    ...
    myFile = locate("appdata", "groups.lst")
    doSomething(myData);
    myData = myReadGroups(myFile);
    ...
    ...
    myFile = locateLocal("appdata", "groups.lst");
    doSomething(myData);
    myWriteGroups(myFile, myData);
    ...
    myFile = locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    </syntaxhighlight>


    * A resource file is read and written. No system default is used if the user has no local version of the file. The resource file is always written to the users local .kde directory.
    <!--T:25-->
    // Code example
    * A resource file is read and written. No system default is used if the user has no local version of the file. The resource file is always written to the users local {{path|.kde}} directory.
    myFile = locateLocal("appdata", "groups.lst");
    myData =  myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);


    <!--T:26-->
    <syntaxhighlight lang="cpp-qt">
    // Code example
    myFile = locateLocal("appdata", "groups.lst");
    myData =  myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    </syntaxhighlight>
    <!--T:27-->
    ''Initial Author:'' Stephan Kulow [mailto:[email protected] ([email protected])]
    ''Initial Author:'' Stephan Kulow [mailto:[email protected] ([email protected])]
    <!--T:28-->
    [[Category:KDE3]]
    [[Category:Architecture]]
    </translate>

    Revision as of 19:13, 11 July 2012


    KDE Architecture - Accessing Standard Resource Directories

    Overview

    KDE offers several ways to access the files that your application installed on your user's hard disc while making it transparent to you where the data really are. To allow the user (or adminstrator in most cases) to move files where he sees them fit best, KDE offers a list of different resource types for which a different search path is assigned to. You may have heard of the environment variable PATH to lookup executables or MANPATH for looking up man pages. You wouldn't expect man to lookup man pages in PATH.

    Similiar to that concept KDE seperates search paths for different things to make it simpler to add paths for a specific resource without making a lookup for another resource unnecessary slower and without requiring you to put everything into one directory.

    The types of resources KDE offers are

    • apps - applications menu (.desktop files)
    • cgi - CGIs to run from khelpcenter* config - configuration files
    • data - where applications store data* exe - executables installed privatly for KDE's use
    • html - HTML documentation* icon - application icons to appear in the window manager or the panel
    • lib - libraries and to be dlopened modules* locale - translation files for KLocale
    • mime - mime types* sound - application sounds
    • toolbar - toolbar pictures
    • wallpaper - wallpapers

    For all of them exist also Makefile aliases that configures created by the development tools provided for KDE (e.g. kdevelop) will know about.

    KStandardDirs

    This is one of the most central classes in kdelibs as it provides a basic service: it knows where the files reside on the user's harddisk. And it's meant to be the only one that knows - to make the real location as transparent as possible to both the user and the applications.

    For this it encapsulates all informations from the application and applications always refer to a file with a resource type (e.g. apps) and a filename (e.g. Home.desktop). In an ideal world the application would make no assumption where this file is and leaves it up to KStandardDirs::findResource("apps", "Home.desktop") to apply this knowledge.

    The main idea behind KStandardDirs is that there are several toplevel prefixes where files are below. One of this prefixes is the one where the user installed kdelibs into, one where the application has been installed to and one is $HOME/.kde, but there may be even more. Under these prefixes there are several well defined suffixes where specific resource types are to be found. For example for toolbar icons that is share/toolbar and share/apps/<appname>/pics.

    So the search algorithm basicly appends to each prefix each registered suffix and tries to locate the file there. To make the thing even more complex, it's also possible to register absolute paths that KStandardDirs looks up after not finding anything in the former steps. They can be useful if the user wants to provide specific directories that aren't in his $HOME/.kde directory as example for icons.

    On the usage of locate and locateLocal

    locate and locateLocal are both convenient functions that make the use of KStandardDirs as simple as possible. You have however the possibility to use the full power of KStandardDirs without them.

    Typical KDE applications use resource files in one out of three ways:

    • A resource file is read but is never written. A system default is supplied but the user can override this default in his local .kde directory:
    // Code example
    myFile = locate("appdata", "groups.lst")
    myData = myReadGroups(myFile);
    
    • A resource file is read and written. If the user has no local version of the file the system default is used. The resource file is always written to the users local .kde directory.
    // Code example
    myFile = locate("appdata", "groups.lst")
    myData = myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    
    • A resource file is read and written. No system default is used if the user has no local version of the file. The resource file is always written to the users local .kde directory.
    // Code example
    myFile = locateLocal("appdata", "groups.lst");
    myData =  myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    

    Initial Author: Stephan Kulow ([email protected])