# The Caitoo Handbook

Matej Koss <koss@napri.sk>
Version 0.6.4, 20 May 1999

This Handbook describes Caitoo Version 0.6.4

Documentation for Caitoo

caitoo
kget
download
resuming
queueing

## Introduction

Caitoo ( formerly known as KGet ) is a download manager similar to Go!zilla(tm) or GetRight Download(tm).

It keeps all your downloads in one dialog. Program supports drag & drop from KDE applications or Netscape. You can easily drop url's from kfm or Netscape onto main window or onto docking window. Transfer will register on the list and you can simply organize them ( add, delete, stop, resume, move around on the list). Status window shows size of each transfer, current progress in percents, current transfer speed and estimated time to finishing of transfer.

Caitoo, as well as kfm is utilizing libkio and kioslaves. This allows using of many sophisticated features like resuming of ftp and http transfers, setting timeouts for read operations etc.

Users can set retry count for transfer, schedule it for later start or simply add transfers to the list without starting them. Caitoo also supports queueing. Transfer list can be exported to / imported from file, and this list can be set to autosave every X minutes. Other features include auto-disconnecting, auto-shutdown, auto-paste and also expert mode for experienced users.

Caitoo can automatically check you Internet connection and start/stop transfers accordingly.

I hope you will find Caitoo useful,

`Matt Koss`

koss@napri.sk

## Installation

### How to obtain Caitoo

Caitoo can be found on http://devel-home.kde.org/~caitoo, Caitoo's home page, or at ftp://ftp.kde.org/pub/kde/unstable/apps/network, the main ftp site of the KDE project.

### Requirements

In order to successfully compile Caitoo, you need KDE 1.1 libraries ( can be found on ftp://ftp.kde.org/pub/kde/ ).

### Compilation and installation

In order to compile and install Caitoo on your system, execute the following commands in the base directory of the Caitoo distribution:

    > ./configure
    > make
    > make install

Caitoo uses `autoconf` package and you should have not trouble compiling it. Should you run into problems please report them to the author of program.

Please note, that Caitoo requires an advanced compiler like egcs or gcc2.8.

## Working with Caitoo

### Starting Transfer

#### Drag and Drop

You can drag URL's from KDE applications ( like kfm or kmail ) or from Netscape into the Caitoo main or dock window. Then you choose directory and filename, under which you want to save it.

#### Opening transfer by hand

You can open transfer from menu or by keyboard shortcuts Ctrl-o or Ctrl-v. Ctrl-v is especially useful if you use a WWW Browser which does not support KDE drag and drop protocol. Copy the URL to the clipboard, then use Ctrl-v in Caitoo ( or simply press a toolbar button Paste transfer ). Caitoo will then open a dialog with pasted URL, which you can edit.

#### Passing URL on startup or in run-time

You can pass URL to Caitoo as an argument on startup :

    > caitoo some_url

The same approach works when Caitoo is already running. Instead of starting another copy of Caitoo, it will add argument ( URL ) as a new transfer.

With a distribution comes also a little shell script called caitooclient. This script does nothing else then invoking Caitoo with arguments and redirecting standard output and errors to `/dev/null`. This might be useful when calling Caitoo from some external programs.

### Transfer modes

Transfer is always in one of the three transfer modes :

#### Queued

Transfer is in a queue, which means that it's ready to be started whenever it's possible. For better explanation see Queueing.

#### Scheduled

Transfer is scheduled to be started at some later time. Caitoo checks every minute whether there is some transfer that should be started. It takes into account the maximum number of allowed transfers. Transfer time is set in Transfer Configure Dialog.

#### Delayed

Transfer is simply added to the list. Caitoo will not try to start it. You have to start it by hand, or change it's mode to queued or scheduled.

This is useful if you work offline, then you can set Add new transfer as delayed in a preferences dialog.

Use this feature if you have problems with connecting to server or slow connection and want to download files later.

### Other features

#### Queueing

Queueing means that you can set maximum number of transfers that are running simultaneously. Caitoo tries to keep this number. Of course that you can at any time start the transfer by hand.

This does NOT mean that you cannot drag more files into Caitoo then this number !

Caitoo keeps record of all registered transfers and opens them when needed. Use queuing when you have bad connection to Internet or slow modem like me :-)

It is useful also when you do not want to take all network bandwidth you can, but rather download file after file.

#### Resuming

Caitoo supports resuming, which is a feature supported by most of ftp servers and is present in HTTP 1.1 protocol. If you download some big file and after 75&percnt; of download connection error occurs, you do not have to start all over again, but simply register this transfer again and it will continue in the place where it stopped ( Caitoo will append to an existing file and not overwrite it ).

However, this feature does not work for all ftp and http servers. Caitoo will check, whether server supports this feature, and will show this infomation in the listbox. Later, if you need to stop the transfer, you can easily decide, whether it is a good idea.

HTTP resuming is somewhat special. Please consider it to be experimental and don't rely on it too much.

#### Expert mode

Expert mode is recommended for experienced users. Generally, when expert mode is on, Caitoo will not ask user to confirm operations.

This applies to deleting of transfer, confirming paste operations and save locations.

If some error occurs while starting transfer or while transfering, Caitoo will not show you the error message, but it will set transfer for retry without asking. This is very useful, if you drag many files into Caitoo and leave to do some other work. Caitoo will download files and when it can't connect, it will continue without asking.

It could be useful to use expert mode together with auto-disconnect / auto-shutdown mode. Drag files into Caitoo, turn on the expert mode, turn on auto-disconnect / auto-shutdown mode and leave.

### Caitoo Key Bindings

Caitoo honors the following key bindings.

`Ctrl-o`

  Open a new transfer

`Ctrl-v`

  Paste in URL for transfer

`Ctrl-q`

  Exit program.

## Screen Fundamentals

### Transfer List

Main part of Caitoo window is listbox, where all transfers get registered. Each transfer is represented by one line in this listbox. Every line is divided into several fields :

- S - Status icon representing current status of transfer

- Local filename - Name under which the file will be saved

- Res. - Indicator, whether this transfer can be resumed

- Count - Number of files as a ratio of processed files / total count of files

- &percnt; - Already processed size

- Total - Total size ( counted recursively in case of directories )

- Speed - Current speed

- Rem. Time - Remaining time to the end of transfer

- Address (URL) - Source URL of this transfer

In order to do any operation on registered transfer, this has to be selected by clicking on it with left mouse button. Use middle mouse button to unselect it.

Pressing right mouse button on transfer opens a menu with some operations. You can move transfer to the end or beginning of the list. You can e.g. select a transfer that is running very slowly, pause it and move it to the end of the list. This file will start download as the last one. This is also a simple way of organizing transfers on the list.

Menu item Copy URL to clipboard will copy source URL of the transfer into the clipboard. This is useful if you have registered transfer and want to download something with a similar name ( right-click on transfer, copy URL to clipboard, press Paste button and edit the name in the window).

Menu item Configure transfer will open transfer configure dialog. See Transfer Configure Dialog.

### Toolbar

Toolbar contains buttons for all operations which can be applied on selected transfer. Not all are enabled at all times. For example you cannot pause already paused transfer. These buttons are grouped together according to their functions.

Left part contains buttons for basic operations. These are Resume, Pause, Delete and Pause all buttons. Their functions should be already obvious.

In the middle part there are three mode toggle buttons : Queued, Scheduled and Delayed. They show the current transfer mode for selected transfer. Use them to quickly change the transfer mode. These buttons are like radio buttons, only one can be selected.

Third part contains two buttons : Preferences, for quick opening of preferences dialog and Paste transfer for pasting of the URL into the Caitoo.

Fourth part contains five global toggle buttons : Expert mode, Use last directory, Auto-disconnect mode, Auto-shutdown mode and Auto-paste mode.

The right most toolbar button is for docking. It's a toggle button. When you turn it on, Caitoo will dock into the panel. See Dock Widget.

### Status bar

Status bar displays all important messages concerning transfer, like when some transfer is resumed or set to retry.

It also contains several fields :

- Transfers - total number of transfers that are in a listbox

- Files - total number of files that remain to transfer

- Size - total size of all files that remain to transfer

- Time - time that remains to finish transfering of all files

- Speed - total speed of transfering

### Main Menu

#### File

Open Transfer

  Prompts for an URL of the new transfer.

Paste Transfer

  Paste a transfer from the clipboard into a Caitoo. You can for example paste here URL from Netscape.

Export Transfer List

  Allows to write transfer list into the file. Later you can import it or you can copy this list into another computer and do your downloads there.

Import Transfer List

  Allows to read transfer list from the file.

Quit

  Quits the Caitoo.

#### Options

Show Status Bar

  Allows the user to have the status bar displayed or hidden.

Use Animation

  Allows the user to stop or start animation of the status icons and dock widget.

Use Sound

  Allows the user to enable / disable sounds.

Preferences

  Brings up the Preferences Dialog. See Preferences

#### Help

Contents

  Invokes the KDE help system with the Caitoo help pages displayed.

About

  Displays essential information about Caitoo.

### Transfer Configure Dialog

This dialog can be used to set the transfer mode and timer. It shows the source and destination URL's.

It is opened also when you set transfer mode to scheduled and you need to set the timer.

### Individual Progress Dialog

When you double-click on some transfer in the listbox, an individual progress dialog will open. Sometimes you want to keep the Caitoo docked, but still you want to watch the progress of some important transfer. You can e.g. iconify this small progress dialog and watch the progress in the taskbar.

Warning !!!

Pressing the Cancel button will not only close the progress dialog, but cancel the whole transfer !

### Dock Widget

Press Dock window on the toolbar to dock Caitoo. After this, Caitoo will be represented on the screen by the small dock widget in the panel.

You can drag URL's on this widget without keeping the main Caitoo window opened.

Dock widget is also an indicator of running transfers. When there are some currently running transfers, this widget shows a bar chart for first three running transfers.

Right mouse button click opens a popup menu, where you can undock widget or quit application.

### Drop Target

Press Drop target on the toolbar to change Caitoo main window into the little shaped window. This little window will be always on the top of all windows. You can use it for drag&drop of URL's. As Dock widget, it also shows progress, but for first four running transfers.

Right mouse button click opens a popup menu, where you can set this window to be sticky or not, or quit application.

### Log Window

Log window shows messages from all events that happen in Caitoo. You can open it by pressing Log window button on toolbar, or selecting it from main menu.

## Preferences

When you press Preferences button in the toolbar or choose same item from the main menu, this dialog will open and allow you to set various Caitoo options.

### Connection

#### Reconnecting

On login or timeout error

  If Caitoo can't login into the server, it will stop attempting and schedule it for retrying after some time. For this you have to set interval - reconnect after X minutes and number of retries.

On broken connection

  If some connection error occurs while downloading, Caitoo will automatically pause all affected transfers ( because of error ) and resume them again ( well not all, only those which can resume, others are only paused ).

Automatically resume

  When this is set, Caitoo will resume transfers without asking ( normally it would open dialog asking whether overwrite or resume ). If transfer cannot be resumed, dialog will appear anyway.

#### Timeouts

These are the intervals, after which when no data arrives, Caitoo will pause transfer and resume it again. The second value is meant for transfers which cannot resume. Of course that this value should be bigger then the first one.

#### Type of connection

Here you can set what type of connection to Internet you have. This is needed, so that Caitoo can automatically activate / disactivate Offline mode. This feature will be probably most useful for users with dial-up connection.

For successful use of this function, you need to now the network interface that is used for your Internet connection.

If you are sure, that you are always online, you can select Permanent in the combo box. With this choice, Caitoo will not check for the connection, but rather assume that you are always online. However, you can still activate offline mode manually ( see below ).

Users with other types of connection might want to set select something else. Easy way of finding out what kind of interface is your network using is an utility ifconfig.

Simple output in the shell might look like this :

    lo        Link encap:Local Loopback
              inet addr:127.0.0.1  Bcast:127.255.255.255  Mask:255.0.0.0
              UP BROADCAST LOOPBACK RUNNING  MTU:3584  Metric:1
              RX packets:128 errors:0 dropped:0 overruns:0
              TX packets:128 errors:0 dropped:0 overruns:0./configure

You can see that first two letters are lo. This is short for loopback interface, which is always running on most systems. The output will probably look like this when you are disconnected from Internet. After connecting to Internet, you might see also another entry, which starts e.g with ppp0 or sl1. These two stand for PPP interface number 0 or SLIP interface number 1. Now you would now, what your connection interface is, and you can set it in the combo box.

Offline mode

  Turn this on when you want Caitoo to be in offline mode. In this mode, you can use Caitoo to create lists of transfers, while actually not downloading anything. It's useful when you are browsing stuff offline, but still want to create transfer list. There is also a toolbar button for quick access to this function.

### Proxy

If you need to connect to Internet via proxy, you can turn on option Use Proxy.

Type in your proxy server and desired port.

In No proxy for line specify servers, for which you don't want to use proxy.

Please note that ftp proxy doesn't work yet and also http proxy is only experimental and might not work always as expected.

### Automation

Auto save file list

  This is interval after which the transfer list gets saved into the config file.

Auto disconnect

  If this is set, Caitoo will automatically disconnect from Internet when all queued transfers are finished. It doesn't care about scheduled transfer. However, when you schedule transfer, you probably have other type of connection then PPP link and you don't need this option. This option can be toggled more easily from the toolbar.

Disconnect command

  Specify here a command for disconnecting from internet. Preset is "kppp -k" , which will stop running kppp. You can of course use anything else, e.g. "killall pppd".

Auto shutdown

  If this is set, Caitoo will automatically quit when all transfers are finished. This time it cares about scheduled transfer. If there is anything scheduled, Caitoo won't quit. This option can be toggled more easily from the toolbar.

Auto paste

  If this is set, Caitoo will automatically paste URL's from clipboard. There will be no need to press Paste button, just copy some URL into the clipboard and it will be pasted automatically. This option can be toggled more easily from the toolbar.

### Limits

Maximum number of opened connections

  Caitoo will keep this number of simultaneously downloading files. This means that Caitoo will not download more then this number of files in the same time.

Start transfer only if network bandwidth is more then

  This feature is not yet supported.

Keep the maximum bandwidth taken by transfer at

  This feature is not yet supported.

### Advanced

Add new transfers as

  You can choose whether the new transfers should be added as queued and thus automatically started, or as delayed, which is better when working offline.

Show download windows

  If this is set, Caitoo will open progress windows for started transfer. You can even choose to start it iconified. This option is good if you e.g. want to watch the progress of some transfer without opening the main window. Iconified window will show progress in the task bar.

Mark partial downloads

  When this is set, Caitoo will add a special extension .part to all downloading files. Caitoo will remove the extension after the successful download. This way you know whether the file was downloaded OK or not. This option is set on by default.

Remove the file from the list after success

  Turn this option off, if you want finished transfers to stay in the list. They will have a special status icon. This is needed if you want to do some statistics about downloaded files.

Get file sizes

  When turned on, Caitoo will for all added transfers get their sizes first and display them in the list. This way you will know the size of the file before downloading it.

Expert mode

  This mode is for experienced users. For explanation see Expert mode. This mode can be toggled more easily from the toolbar.

### Directories

In this section you can setup default directories for different file extensions. Each line in the list contains a pair : file extension and directory.

Buttons allow you to add, delete and change entries in the list.

You can use wildcards in the the extension field to specify various file types.

When the new transfer is added, the file extension is compared to the entries in this list. Caitoo keeps the order, so put more global entries ( like * ) to the end of the list.

When Caitoo doesn't find the matching extension, it will use the current directory.

Toolbar button Use last directory can be used to temporarily disable the directory settings. When it is set, Caitoo will put the file into the directory used for the last transfer added.

### System

Use Sounds

  If this is set, Caitoo will play sounds when one of the four events occur :

  - transfer was added to the list

  - transfer has started

  - transfer has finished

  - all transfers have finished

  This way you do not have to watch the Caitoo window ( you can leave it docked into panel, so that it does not take any place on the screen ) and Caitoo will notify you when transfers are added / started / finished. If you cannot use sound - leave this option disabled. Caitoo comes with four default sounds for these events. If you don't like supplied sounds, you can of course change them. Choose sound for change in the combo box, change it by pressing Change button and test it with Test button. In order to use sound you have to start kaudioserver first. It comes with KDE distribution and normally it is already started from startkde script. You can toggle this option also from the main menu.

Use Animation

  If this is set, Caitoo will animate status icons in the listbox and also use animation in the docked widget. You can toggle this option also from the main menu.

Window Style

  Here you can set, how will Caitoo appear on the screen. It can be either as a normal window, dock widget or drop target. See Screen fundamentals for more details on each type.

Windows 9x Style of docking

  This toggle is for selecting beteen two styles of docking / drop target.

  When it is on, dock widget or drop target behave like in Windows 9x. When you click on them, they will undock / change into the normal Caitoo window.

  Other way is like it was in former version of Caitoo. Clicking on dock widget or drop target will show / hide normal Caitoo window.

Font

  Use font dialog to set your favourite font for a listbox.

## Questions and answers

- Why should I use Caitoo and not just kfm ?

Why should I use Caitoo and not just kfm ?

If you use to download only one file at a time, kfm is probably enough for you ( if you do not need resuming ). Caitoo is utility for people who want to download many files and do not want to look at many progress dialogs.

Caitoo is independent from kfm. This means that when kfm dumps core ( though it doesn't happen too often since KDE 1.0 ), Caitoo still works and transfers files.

However, Caitoo is intended to closely cooperate with kfm as it uses KDE drag and drop. Use kfm to browse web and when you see something that you need - just drag it onto Caitoo window and browse away. You do not have to remember the URL of the file anymore - Caitoo will take care of it. And when Caitoo can't connect - you can still leave transfer on the list and try to connect later.

Another thing is queueing. You can set number of transfers and then use Caitoo as before. Caitoo will only start specified number of transfers, and keep others queued. Later, when first transfers finish, Caitoo will start queued ones.

## Copyright

    Caitoo is Copyright 1998-1999 by Matej Koss,
                                  koss@napri.sk

    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.

### Thanks

Thanks to the guys who wrote programs GetRight Download and Go!zilla ( for Windoze ) - sorry, but I don't know your names - which gave me the idea for this program, even if I didn't use any code from them.

Thanks to many users, who have contribute their bug reports / fixes and requests for new features to me.

Thanks to the authors of KDE, wonderful desktop environment.

Thanks to the Trolls for Qt, a great library.