# The KFM Handbook

The KDE Team
05/06/1998
1.83.00

This Handbook describes KFM 1.83

kfm
file
manager
KDE

## Introduction

KFM is KDE's file manager. At the same time it is a full featured web browser, ftp client and tar archive utility and it acts as a server for other KDE applications, since it offers its network service that make up KDE's network transparent file access.

`Torben Weis`

weis@kde.org

## Philosophy

### Desktop

The desktop metaphor< is very important for KFM. Many filemanagers in the UNIX world work only in their windows. But KFM gives you a Desktop like OS/2, Apple and ( I hate to say it ) Win NT/95. Files on the desktop work like the ones in the windows. Since KFM supports drag and drop it is a good idea to use the Desktop for storing some temporary things. On the other hand it is always nice to have some important icons always handy on the Desktop. Well, just do what you want

### Templates

Templates have been introduced by OS/2. KFM has some - not really that powerful but never the less nice - feature to support them. All files in the Templates directory are supposed to be templates ( I think you would not have guessed that! ). Move for example an template for a Lyx letter in here, or a default Makefile or whatever. Even complete directory structures may act as templates. If for example a project you start always has the same directory structure, you can create such a structure in the templates directory. Then you change to the directory where you want to have a new document/project/what-ever. Open the Menu `File` and there the submenu `New` and you will get a list of all installed templates. Just select one to create it. This way you can create directories, too. The idea is simple but useful.

### *.kdelnk files

These files are important for KFM and kpanel and the whole KDE project. Such a file can do very much for you. For example it can hold an URL or a device or may stand for a program. Using such a file you can mount/unmount devices, make links to URLs on your desktop or just create a nice icon represantation for an executable. Read the section 'Usage' to learn more about these files and what they can do for you. You dont need to know how the files are structured, because KFM has nice dialogs for you, so you can click some `*.kdelnk` files in existence very easy. If you drag for example a URL pointing to `ftp://ftp.kde.org` on your desktop, KFM will create such a file for you. Clicking on it will open a FTP connection for you.

### Internet

The Internet is very important for KFM, too, because it could be called an internet desktop. It uses FTP and HTTP. This means that KFM makes no big differences between files on some FTP server or on your local hard disk. Since KFM uses HTML to show its output it has no problem with HTML pages. This means that you can follow HTML links like you would do with your browser. Indeed KFM acts like a Web-Browser many times. It is indeed a Web-Browser with integrated file management. The HTML widget is not perfect yet, so some HTML pages are ugly, but it is getting better all the time. As a result of the above KFM uses URLs instead of usual file names ( of course you can use your old fashioned file names, too ). KFM supports an extension to usual URLs. It features subprotocols. Ususally the user does not have to deal with them, he may still click around with the mouse. For example `ftp://ftp.cdrom.com/unix/kde.tgz&num;tar:/kdebase/kfm/main.cpp` is a valid URL. It defines a tar file on an ftp server and references some file in the tar archive. Clicking on some tar archive will do the job for you.

### Multi Tasking

KFM is highly multi tasking. It has some slave processes running that do the IO stuff. This means that no IO can block your desktop. This is especially important for the Internet. You know that even Netscape can lock up for some seconds. KFM does not have this problem any more. It just locks up if you found a bug.

### Look

KFM gives you control over the look of your directories. If it finds a `.kde.html` or `index.html` file in your directory it displays it ( can be turned off ). There are some HTML extensions that allow you to separate for example directories and documents on such a HTML page. You need not write a link for every file in the HTML page. The HTML extension helps you very much here. Instead of writing a complete HTML page you can select a background color/image for some directories and change the color of the font. You may give executables and directories special icons. Those icon settings are recognized by kpanel, too. For more details see as usual the section 'Usage' in the handbook.

## Usage

You are reading a manual, so I conclude that you ran into problems. So take a good advice first:

Now you should feel a bit better, but before you can face what is coming next, you should go to your next bookstore and buy Douglas Adams famous trilogy in 5 books...

Read these five books `:-)`

I hope you are relaxed and happy now and well prepared for the incredible rest of this hitch hikers guide to KFM.

Keyboard shortcuts.

### Keyboard shortcuts

    Back in History                                 ALT + Left
    Forward in History                              ALT + Right
    One directory up                                ALT + Up
    Open a file/directory                           Return
    Open a popupmenu for the current file           ESC
    Move among the icons                            Left/Right/Up/Down
    Select/Unselect file                            Space
    Scroll up fast                                  Page Up
    Scroll down fast                                Page Down
    Scroll right (on WWW pages)                     Right
    Scroll left  (on WWW pages)                     Left
    Scroll up    (on WWW pages)                     Up
    Scroll down  (on WWW pages)                     Down
    Copy selected file to clipboard                 CTRL + C
    Paste files from clipboard to current directory CTRL + V
    Select files by pattern                         CTRL + S
    Open a terminal in the current directory        CTRL + T
    Open new location                               CTRL + L
    Find files                                      CTRL + F
    Close window                                    CTRL + W

### How to install new data types

#### What are data types

A file contains only bits and bytes. One must know how to interprete them to give them a meaning. A usual method to archive this is to look at the filename. If it ends with `.gif` for example, you assume that it is a GIF image. That's what most desktop environments (further on called DE) do. KFM does this, too, since it is very fast, but not convenient. If the extension is not available one does not know of which data type the file is and that means in turn that KFM does not know which appliaction can deal with the data. So if KFM can not figure out the data type by extension it will have a look in the first bytes of the file and lookup some stuff in its magic file. This is called automatic-mime-type-detection-magic and works quite nice. So if the datatype has an entry in the magic file `$KDEDIR/share/mimelnk/magic`, then KFM would know that the file `MyGirlFriend` contains an image.

You must register data types in KFM. This poor little helper of yours must know common extensions of this data type, an icon, some descriptive text, perhaps a default application ( we will learn more about this later ) and the mime type.

#### What is a Mime Type

Mime types are an internet standard. This standard is a naming scheme for data types. A data types name is devided in two sections. The first one tells about the general kind of data ( image, video, audio, text ... ) and since there are different kinds of text ( C-sources, english text, ... ) and different formats for saving images and so on, the second part tells abou the special format. A good example is `image/gif`. The first part tell, its an image and the second one tells, it is saved in GIF format.

If you are not shure about the correct mime type, then have a look at the magic file, many many mime types are already registered there.

Usually this chapter is only of interest for system maintainers and application developers. A proper installed KDE should come with all this stuff already done, but some people always want to know how stuff works, so here we go.

The directory `$KDEDIR/share/mimelnk` contains many subdirectories which correspond to the first section of the mime type names. For example our example `image/gif` is represented by a file named `$KDEDIR/share/mimelnk/image/gif.kdelnk`. Every KFM config file has the `.kdelnk` extension. Sometimes KFM hides this extension, since it does not look very nice.

You will find out sooner or later that the directory structure in your global KDE directory is the same as the one in your `˜/.kde` directory. As sysadmin on your local Linux box, you may usually want to edit the global configuration, while a user at the universities UNIX cluster may only edit his personal configuration. Everything we say about the `$KDEDIR` directory here, applies to the `˜/.kde` directory, too. To edit the global config files in `$KDEDIR` you need a super users password, for the personal stuff of course not.

#### Installing new mime types step by step

This chapter could be named installing mime types for dummies since it comes with many nice pictures `:-)`.

In the following we want to see how I installed the `image/gif` mime type. You dont need to reproduce these steps, since this mime type is already installed. After reading this chapter and after having a look at all the images you should know how to install new ones.

The black numbers on yellow circels in the images correspond to the numbered list under the image.

##### Open a KFM super user window

On your desktop you will find icons like these:

Now click on this icon to open a new KFM window. Usually this is the correct method, but in some cases we need a super users KFM window. If you want to edit the global config files which are usually only writeable for the super user, you need super user access. If you dont now the super user password, then you are not allowed to change the global configuration anyway, but you can of course edit your user specific configuration without being super user. There are different methods leading to a super user kfm window. You can log out, and log in as root. That is the Windows NT way, so we want to do it better. You could open a kvt window, switch to superuser with `su` and start `kfm -ws` now, but it is much easier to hit `Alt+F2`. Now enter `kfmsu`. A terminal window pops up, asking you for super users password. Enter it and a KFM window will popup up. Once you have done the following stuff, dont forget to close the KFM super user window again. At this time the terminal will desappear, too. the `kfmsu` script will allow the super user to access the display and will disallow it afterwards automatically for you.

To start, click once with the left mouse button on `Templates` folder ( or open a super user KFM window as described above ). Have a look at the files in this directory, you will remember them later in this chapter.

Now open the menu `Edit` and choose `Mime Types` ( or `Global Mime Types` if you want to edit the global configuration ). Now you will see something like this:

- This is the magic file we talked about before. You should have a look at it later, but dont worry, no need to understand it.

- The folder containing the `image/gif` mime type file. Click on this folder with the left mouse button to open it.

##### Creating a new mime type file

Open the menu `File` and select `New`. You may have notice by now that the names in this popup menu correspond to the names in the tamplates folder. This menu gives you quick access to the templates. You can have the same effect by opening the templates folder and doing drag and drop. Now select `Mime Type`. A window like this one will popup:

- Enter the name of the file here. Please dont delete the `.kdelnk` extension. You should notice here that the name of the file is only the second part of the mime types name. The first part is coverd by the directory you move the file in. The name of the file and the subdirectory you put it in does not really matter, it just needs to be in `$KDEDIR/share/mimelnk`.

- Now press the OK button and the new icon will appear in the KFM window.

##### Opening the properties dialog

Now press the right mouse button over the new icon and select `Properties` from the popup menu. A dialog appears:

- Select the tab called `Binding`.

- Enter some patterns that usually match files of this data type. If you have multiple patterns, then you must separate them with a `;`

- Enter a descriptive text here. If your language is supported, you will notice that the description is in your native language. KFM can store multiple descriptions, one for each language. If you enter something here then it will be stored under your language. Application developers should make shure that at least a english description is available. How to do this was discussed one chapter before in the hackers section.

- Enter the full name of the mime type.

- You can select a default application here. This is of interest if multiple applications regsitered for the same mime type. If you click on such a data type file KFM makes a guess which app to use. By choosing a default app you can keep KFM away from guessing.

- Select a icon. All icons are stored in `$KDEDIR/share/icons`. For every icon in this directory there exists a icon of the same name but half size in `$KDEDIR/share/icons/mini`. Usual icons have the size `32x32` and the mini icons `16x16`.

- Press the OK button.

Now KFM rescans all opened directories because the icons and stuff could have changed. You can force KFM manually to do so by choosing `Rescan Bindings` in the `View` menu. Your mime type is now registered and KFM should know about it.

Congratulations, you survived this lesson. Time for a break now `:-)`

#### Internals

The config files are very simple and of course human readable. You can have a look at it here:

    # KDE Config File
    [KDE Desktop Entry]
    Type=MimeType
    MimeType=image/gif
    Icon=image.xpm
    Patterns=*.gif;*.GIF;
    Comment=Gif images
    Comment[de]=GIF Dokument
    Comment[nl]=Gif afbeelding

You dont need to understand what this means, since KFM provides a GUI for you, that makes things much easier. Hackers never the less want to know and hack everything, so here is a brief description.

The first line is the header of every KDE config file. The `Type`line is included in every KFM config file to distinguish the purpose of the config file. This is followed by the mime types name, the icon, a `;` separated list of patterns and comments in english, german, ...

Now the hackers may leave this lesson.

### How to install a new application

Every KDE application should come with its configuration files so there is no need for the user to edit them. But unless every distribution is KDE ready you may want to configure existing applications to work with KDE. In this lesson we try to install XV in the K Desktop Environment.

#### Why and where

Every application must put a config file in the directory tree `$KDEDIR/share/applnk`. In addition you have a local directory structure in `˜/.kde/share/applnk` where you can install additional apps. These files will only be visible for you, not for other users. KFM and KPanel scan these directories on startup. KPanels system menu corresponds to this directory structure. The icons in this directory behave like real applications. You can click on them to start the application and you may drop files on them. It is sometimes a good idea to have such config files outside the `applnk` tree. They work in every directory, but only the ones in the `applnk` directory are scanned in on startup. So if you want to install for example XV as the default app for images, then you must move the config file inside this special tree. But perhaps there are some apps which you dont want to appear in KFM or KPanel but on your desktop, then you may of course create such config files on your desktop or elsewhere. The procedure is almost the same as the one we are describing here.

If KFM find a file it first tries to find out about its data type. After doing so it searches all applications which regsitered for this data type. If none is found the user is prompted. If only one is found or a default on was specified, KFM will use this one, otherwise KFM will make a guess. Using the right popup menu will show you a selection of all applications which registered for this data type.

#### Step by step

You may now continue with the next section while the hackers and developers may want to learn more internals.

The config file we want to create will look like this:

    # KDE Config File
    [KDE Desktop Entry]
    BinaryPattern=xv;
    MimeType=image/gif;image/jpeg;image/tiff;image/x-xbm;image/x-xpm;
    Comment=XV Image App
    Comment[de]=XV Graphik Programm
    Exec=xv %f
    TerminalOptions=
    Icon=image.xpm
    Path=
    Type=Application
    Terminal=0
    Name=XV
    Name[de]=XV

The first line contains some magic bytes and the second line contains a `;` separated list of names that the binary of this application may have. This way the binary gets a nice icon, too. The next line conatins a list of all mime types the app can handle, followed by the usual comments in different languages. the `Exec` tag contains the shell quoted command that will be executed to start the application. The `&percnt;f` is going to be replaced by the documents filenames, but see the next chapter for more details. The `Type` tag is needed like in every KFM config file. You can tell KFM to start the app in a terminal by setting `Terminal` to 1 and by setting some terminal options if needed. In addition the `Path` tag allows you to specify a working directory. The last two lines determine the name of the applicattion. This name is used in KFMs context sensitive popup menus for example. As with the comments you must provide a english version and may supply diffrent translations.

#### Secret tips

Most old style apps may need the `&percnt;f` argument. This means that they can only accept files on the local hard disks. If you use URLs never the less, KFM will download the files first and start the application afterwards. If the files are modified by the app, the user is prompted wether he wants them to be uploaded.

You may enter `&percnt;u` instead of `&percnt;f`. This will cause KFM to pass URLs to the application. External files are not preloaded. Some KDE apps support this cool feature.

There are addtional tags you may use. Here is a short list:

- `&percnt;k` The path and name of the config file itself. This is useful if the app you want to start should read/modify the config file that started it. This way you can for example implement simple printer representations. The same file that repesents the printer on your desktop stores your prefered printer settings. Use `&percnt;k` to pass the config file to the printer GUI.

- `&percnt;n` The filename of the documents without path.

- `&percnt;d` The path of the documents without file name. The `&percnt;d` and the `&percnt;n` tag together are the same as `&percnt;f`.

- `&percnt;c` Name of the application. This is the (possibly translated) title of the application, as set in the kdelnk file. This way you can set the title of the application.

### Integrating an application step by step

In this chapter I will show you how to register XV in the K Desktop Environment. After following these steps XV will be registered for various image data types and will be able to load and save images from the web... you did not expect that `:-)`. So, here we go.

#### Opening a KFM super user window

I assume that you know from the previous lesson how to open a KFM super user window. Now open the menu `Edit` and select `Applications`. You will now be shown a window like this one:

- Here you can see the directory we are visiting right now. This directory tree contains all informations about registered apps in your KDE.

- Now click on this folder, since we want to install XV in the graphics section.

If you are logged in as super user you will find an option to edit the global application config files, too

Please distinguish exactly between applications config files and application config files. The first one stores configurations written by an application during run time, while the second ones ( these are the ones we are talking about here ) contain informations about installed applications. These config files are created during installation of an application and dont change usually afterwards.

#### Creating a new application file

From the menu `File` open the submenu `New` and select `Program`. You will now be prompted by a new window:

- You must enter the applications name here followed by the extension `.kdelnk`. The name you use does not need to be the name of the binary. It may be any name but it has to be a unique name for the app.

- Now press OK.

#### Opening the properties

You will now see a new icon in the window. Press the right mosue button to open the properties menu. Now you have to fill out a form like this one:

- Select `Execute` to see this form.

- Enter the command line which starts the app. This is the same you would enter in a terminal session, but instead of the data files, you must place a `&percnt;f` here. In the hackers section of the previous chapter you will find more information on this place holders.

- In seldom cases one needs to define a working directory for an application. Usually this line is empty.

- Choose an icon for the application.

- Select this checkbox if the app must run in a terminal. This is the case for pine for example.

- You may enter special special command line aarguments here which will ba passed to the terminal ( usually kvt ).

#### The second form

The last step is to fill out the second form:

- Click on `Application` to reach this page.

- You may enter the names of binaries here. Multiple binaries have to be separated by `;`. This causes every binary of this name to become the applications icon, too. So this line is for better look & feel only.

- Enter a small comment in your language here. Developers must take care that there is at least a default english comment provided at the end.

- This list contains all mime types that this app can handle.

- Use this buttons to move mime types between the two lists.

- This list contains all registered mime types which are not handled by the application.

- Press Ok

That is the end of the show, your application is registered now. KFM has updated its bindings automatically, only KPanel will need to be restarted ( System menu of kpanel ). XV should now appear in the list of applications once you hit the right mouse button over an image file containing one of the selected data types. If the image is not located on your local hard disk, KFM will download it and run XV afterwards. If the file is modified by XV, KFM will ask you wether it should be uploaded. It is now time for a coffee or two.

### Bookmarks

KFM enlarges the meaning of bookmarks. Bookmarks can refer to every file, that means apart from HTML pages and FTP directories documents, applications and `*.kdelnk` files. If a bookmark is selected in KFM, the convenient action follows; a document is opened, an application is started etc. To add a file to the collection of bookmarks, you only have to use the right mouse button on the file and select the entry 'Bookmarks'.

#### Editing Bookmarks

Each bookmark corresponds to a file in $HOME/.kde/share/apps/kfm/bookmarks. An entry in the bookmarks menu makes it easy to find this directory. Renaming a bookmark file also changes the bookmark menu immediately. If you open the properties for such a file, you can configure the bookmark, i.e. for example change the destination (URL) or the icon. You can move, copy and rename files in this directory tree as you desire. Please make sure that these files have a suffix `*.kdelnk`, so that KFM will easily distinguish them from 'normal' files.

#### Bookmark Tree

Creating a new directory in $HOME/.kde/share/apps/kfm/bookmarks will create a submenu of the bookmark menu at the same time. To add a bookmark to the new submenu, pop it up. The first entry will add a bookmark for the current URL.

#### Bookmarks outside KFM

The program krootwm allows the access on the bookmarks. Clicking the right mouse botton on the background of the desktop makes (besides other stuff) the bookmark menu appear. Changings on the bookmarks are not immediately applied to krootwm yet. At the moment you have to restart krootwm to do so.

## Frequently Asked Questions

### How can I run programs on startup

KFM can do even more. Throw a program, *.kdelnk file, exectuable, directory or a link to any of them in the `Autostart` folder on your desktop. The Autostart folder has the path `$HOME/Desktop/Autostart` by default, but you may have a different setup, since it is configureable. If KFM finds a kdelnk file, it does what you would epect by clicking on the file. Throwing a directory in the autostart folder will open a KFM window with this directory, executables will of course be executed. But you may put documents! in the autostart folder, too. In this case KFM will start the default application for this document with the document as argument. You can use this to start for example the word processor with your master thesis whenever you login. You may find it useful to put `kdisplay -init` and `kpanel` in the autostart folder. The autostart folder can be used as a replacement for `.xinitrc`

### How can I start KFM without any opened window

Many people think that it is annoying that KFM always opens the home directory. You may start KFM with the option `-d` to avoid this behaviour.

### How can I open a new view for a directory

Clicking with the left mouse button will change the directory, execute an executable or open a document. One click with the right button opens a menu and a click with the middle button on directories will open a new window for this directory.

### How can I select multiple files

Press the CTRL key and click once on every file you want to select. Pressing the right mouse button now will show you all actions that apply to all files you selected. This way you could start multiple documents at once or delete/copy/move a couple of files. If multiple files are selected and you start a drag then all selected files are dragged.

### How can I mount a device

To mount a device you first need a *.kdelnk file that describes the device. If you dont have one already, you must read the section 'Usage' in this handbook to see how to create such files. Once you have done this you may press the right mouse button over the devices icon. Now you have several mount options. Unmounting works just like this. Before you can access a device you must mount it first. Once the device is mounted you can open it with a click. Sometimes it is possible to mount several file systems. But if the default one is the correct one, then you may click on the umnounted icon once and KFM tries to mount the device and will then open a window to show you the content.

### How can I print

You can throw a document on the printer icon. Now it is up to your printer daemon/filter. Usually it only makes sense to throw TeX/DVI/PS/ASCII files on the printer. Be careful. In the worst case your printer may dump out lots of papers with the ASCII codes of the document you wanted to print. Dont forget to open the properties dialog of the printer first to check wether the print command is ok on your system. If you dont find printer icons on your desktop the you must consult the section 'Usage' in this handbook. to see how you can create such a printer icon.

### How can I link a URL on the desktop

You can link any URL in any place on your hard disk. Open the `Templates` folder or use the menu `File->New` to copy/create a new `URL.kdelnk` file or something like this. Open the properties menu and enter the URL. That's all. If you have a link to this URL in a KFM window or in any app that supports DND, you may drop the link on every KFM window or on the desktop. Then click on `Link` in the popup menu and KFM will create a `*.kdelnk` file for you on the fly.

### How can I look in a TAR file

You just have to click on the `*.tar.gz *.tar *.tgz` file to have a look at it. You may now delete files or drag files out of the tar file. Some apps support loading documents out of tar files. You may for example use KView to open an image that is located in a tar file.

## Credits

### Author

My name is Torben Weis. I am a student of computer sciences at the University of Frankfurt, Germany. Feel free to contact me and send me your reports, wishes, some cookies or whatever. I am a poor student and always hungry!.

### Thanks

KFM would not be what it is without so many people sending me bug reports, writing patches and extensions and many good ideas. Thanks to you all. There are some persons which I want to mention in detail:

- Martin Jones wrote most of the HTML widget and is doing the painful job of bug fixing it and catching up with Netscapes latest broken HTML features.

- Fritz Elfert wrote the automatic mime type detection stuff at KDE-ONE in Arnsberg.

- Stephan Kulow did the automake and autoconf stuff and introduced me to the mysteries of CVS and is my last help in questions of platform independence.

- Stefan Westerfeld rewrote the kioslave for KFM II.

- Claudia Sorg, my girlfriend, she had to face my bad moods whenever KFM crashed again and it crashed very often.

### Copyright

    KFM is Copyright 1997-98 Torben Weis weis@kde.org

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.