# The &knewsticker; Handbook

Frerich
Raabe

    raabe@kde.org

2001
Frerich Raabe
&FDLNotice;
2001-01-24
1.00.00

&knewsticker; is a news ticker applet for the &kde; 2.x panel (also known as &kicker;).

KDE
KNewsTicker
kdenetwork
news ticker
applet

## Introduction

&knewsticker; is an applet for the &kde; panel (also known as &kicker;) which provides an easy and convenient way to access the news as reported by many news sites (such as Slashdot, Linux Weekly News or Freshmeat).

To archieve this, &knewsticker; requires the news sites to provide a special RDF or RSS file, which contains the headlines as well as pointers to the corresponding full articles. Such files are very common these days, and &knewsticker; already comes with a selection of good news sources which provide such files.

### Brief Info On RDF Files

RDF files are becoming more and more popular these days, and this applet is not the first application which takes advantage of them. But what are RDF files? This section tries to give a brief answer to this questions, as well as pointers to other sources for further reference.

RDF is an acronym for Resource Definition Framework . It has been invented by the World Wide Web Consortium and is one of the first applications of the Extended Markup Language ( XML)). RDF files (as well as the very similiar RSS files) define and describe so-called Metadata, &eg; information about information.

RDF files can be used for all kinds of Metadata, not just news. Nevertheless, they have become very popular among the news sites as they provide a clean, simple and portable way to distribute news. The news sites provide a RDF file which basically contains a set of records, and each record consists of a headline and an URL which points to the complete article. Besides that, the RDF file contains also the official name of the news site as well as other general informations which are parsed and evaluated by &knewsticker;.

Of course, this is only a short and highly incomplete attempt at explaining the basic ideas behind RDF files and Metadata. If you're interested in this topic, you might want to visit any of the following links which point to further and more complete sources on this:

http://www.oasis-open.org/cover/rdf.html

  This page is a fairly well explanation of the Resource Definition Framework and provides a great list of links to more sites which deal with this topic. No special knowledge is needed to understand this page, and it's highly up to date.

http://www.ccil.org/~cowan/XML/RDF-made-easy.html

  Here you can find a more pratical point of view on the Resource Definition Framework. This page demonstrates the usage of RDF files and shows why and when they are appropriate. The reader should be familiar with the XML 1.0 standard as defined by the World Wide Web Consortium before reading this text.

http://www.andrew.cmu.edu/user/mingfai/rdf/

  This is a great and very comprehensive list of sites which deal with RDF files. You might want to consider bookmarking this page for further reference, as it's also fairly up to date and lists virtually no dead links.

http://www.w3.org/RDF/

  The authoratative source directly from the World Wide Web Consortium. It features a comprehensive list of links to other sites on the topic as well as a timeline of the RDF development, an overview over the architecture, an archive with articles about RDF as well as a carefully assembled list of tools for developers who intend to work with RDF.

If you find any other sites or documents on this topic, don't hesitate to send them to Frerich Raabe raabe@kde.org so that they can be included in this document and help everybody.

Thank you very much!

## Starting &knewsticker;

Here's a screenshot of &knewsticker; in &kde;'s panel
Here's a screenshot of &knewsticker; in &kde;'s panel

&knewsticker; is started like every other &kicker; applet, you just have to add it to the panel (or any child panel of the main one). To do so, just choose News Ticker from the Applet submenu of &kicker;.

Here's a screenshot of &knewsticker; in it's own child panel
Here's a screenshot of &knewsticker; in it's own child panel

Another good way to use &knewsticker; is to put it into it's own child panel. Just add a new child panel by choosing Add Extension Child Panel from the context menu of &kicker;. Now you can simply load &knewsticker; into the child panel as described above.

## Configuring &knewsticker;

As &knewsticker; aims for tight system integration, there is more than one way to adjust the way it works:

Via &kcontrol;

  Start &kcontrol; by clicking on the button in the &kde; panel or choose the corresponding entry in the K menu. Then browse to the &knewsticker; module in the tree view at the left by choosing News Ticker in the Personalization submenu.

With the right mouse button

  You can open the context menu for &knewsticker; by clicking on it with the right mouse button, or clicking on the button with the arrow on it and choose the the entry labelled Preferences in the menu.

### General Configuration

#### Global Options

This is what the General tab of the preferences dialog looks like, when opened via &kcontrol;.
This is what the General tab of the preferences dialog looks like, when opened via &kcontrol;.

No matter what way you've chosen to access the configuration dialog, you will be presented the first tab of the preferences dialog, labelled General. Here you can define how fast the text should be scrolled around, what it should look like as well as other options for the applet. Here is a brief info on what each of the switches and buttons on this tab does:

News query interval

  Here you can define in what intervals &knewsticker; queries the configured news sources for new headlines. This depends generally on how fast you'd like to hear about news and how much load you want to put on the network:

  - A lower value (lower than 15 minutes) enables you to be notified about news very quickly if you want or need to. Please note, that it increases the network traffic significantly, though. Therefore, such low values shouldn't be used if you query popular news sites (such as Slashdot or Freshmeat) as they have generally already enough work with processing the incoming queries.

  - A higher value (higher than 45 minutes) won't make you hear about news that quick. For non-timecritical applications, it should be suitable, though. The positive aspect of longer intervals is that only very little load is put on the network; this saves resources and nerves, for you and the system administrators of the news sites you query.

  The default value (30 minutes) should be appropriate and reasonable in most cases.

Use custom names for news sites

  Check this box to make the news ticker use the names you specified in the list of news sources (available on the tab labelled News sources) instead of the ones the news sites themselves report. This can be handy for news sites which report a very long or useless name.

Endless scrolling

  Check this box to avoid that ugly break and the end of the scrolling (when all the headlines have appeared once). If endless scrolling is enabled and the last headline has been shown, &knewsticker; will attach the first headline to the end of the scrolling text.

Scroll the most recent headlines only

  Check this button to show just the most recent headline for each news site, instead of showing every headline available from every news site.

#### Visual Options

Scrolling speed

  This slider lets you define how fast the scrolltext should be scrolling. If you have rather little space on your taskbar (and therefore a rather small news ticker), you should probably set this to a lower value so that you have a chance to read the headlines. For wider news tickers (and better eyes), a faster text is probably appropriate so that you have to wait for the next headline only as little as possible.

  This value defines, after which period of time the text shall be scrolled a little bit further, &eg; this value is antiproportional. This means that lower values result in a faster scrolling text.

Direction of scrolling

  These options allow you to define in what direction the text should be scrolled, &eg; to the left or to the right, upwards or downwards.

Scrolltext font

  Click on the button at the right labelled "Choose font..." to choose the font which will be used for the scrolling text.

  Certain fonts are harder to read that others, especially when they're used for a scrolltext, so you should probably choose a font which can even easily be read if it's moving.

Foreground color

  Click this button open a convenient color-selection dialog which lets you choose the color which will be used for the foreground of the scrolling text (&eg; the color of the text itself).

Background color

  Click this button to open a convenient color-selection dialog which lets you choose the color which will be used for the background of the scrolling text.

Highlighted color

  Click this button to open a convenient color-selection dialog which lets you choose the color which will be used for the color of the headlines when they are highlighted (when you move the mouse over them).

Underline highlighted headline

  Check this box to have the currently highlighted headline (&eg; the headline which is currently under the mouse cursor) underlined.

### Configuration Of The News Sources

This is what the News sources tab of the preferences dialog could look like, when with the Preferences in the context menu of &knewsticker;.
This is what the News sources tab of the preferences dialog could look like, when with the Preferences in the context menu of &knewsticker;.

Besides the options available on the General tab, there are even more ways to customize &knewsticker; to fit your needs available on the News sources tab. This page mainly consists of a table which lets you manage and maintain the list of news sites &knewsticker; queries for news. Click on any entry with the right mouse button to open a context menu which lets you remove the current entry, or add a new entry with the properties of the selected entry.

At the bottom you can also find two buttons with an up arrow and another one with an arrow which points downwards. These two buttons allow you to move the entries in the list upwards and downwards, which is useful if you would like to define a specific order in which &knewsticker; loads the news sites.

If you have the applet started, you can play around with the settings now. Pressing Apply makes the applet use the new settings immediately, you don't have to restart it.

#### Adding A News Site

There are four ways to add a new news site to the list:

- You can click on the button labbeled Add at the bottom.

- You can click with the right mouse button on the table and choose Add news source. This adds a new entry and sets the name to Unknown.

- You can click with the right mouse button on any entry in the list and choose Add news source to add a new entry which has the same properties as the entry you clicked on.

- You can drag any RDF or RSS file from another application (such as &konqueror;) onto the table. This adds a new entry to the list, sets the name to Unknown and sets the maximum number of articles to 10.

There's actually another, fifth way of adding a new news site to the list: you can click on any RDF or RSS file in the &konqueror; filemanager to have it added to the list immediately.

#### Modifying An Existing News Site

To edit an existing entry in the list, you can use the input fields at the right, which are in the box labelled General . They're normally deactivated, as long as you didn't select any news site in the list. As soon as you select one, though, the input fields are enabled and you can edit the properties of the selected news site as you wish:

- The topmost input field which is labelled Name: lets you edit the name of the news site. The name defined here will be used if the applet was unable to connect to the news site, or if the checkbox Use custom names for news sites (on the General tab) has been checked.

- The input field below lets you edit the URL which points to the RDF or RSS file to be used for the entry. You can change this string either by hand (&eg; by typing in the input field) or by clicking on the small button at the right of it (which has a folder icon on it). That button opens a convenient file-selection dialog which lets you browse to the desired file

- Finally, there's a place to define the number of articles &knewsticker; should download and keep from the news site. The default is 10 articles, but it might be reasonable to adjust this value for some news sites.

When you change the value/text in any of these input fields, you can see the change take effect immediately in the list.

#### Removing A News Site

Of course you want to remove a news source from the list somewhen. To do this, you can either

- click with the right mouse button on the entry you would like to delete and choose Remove news source from the popup menu.

- select the entry you intend to erase with the left mouse button and then click on the button and the bottom of the list labelled Remove.

In both cases, a confirmation box will pop up and make sure you didn't select the wrong entry.

## Using &knewsticker;

Using &knewsticker; is fairly straightforward and should give you no big problems, assuming that you already configured &knewsticker; No matter whether you are running &knewsticker; in the main panel or it's own child panel, it appears as an area with a scrolling text and a button with a small arrow next to it.

### The Applet

The area (it is white per default, but you can change the background color easily using the preferences dialog) with the scrolling text in it is called the news scroller. It keeps scrolling the downloaded headlines (or just the most recent headlines) continuously and provides easy access to the articles. If you see an interesting article, just click on it to open the &konqueror; web browser, showing the full article which belongs to the headline you clicked on. If you feel that a possibly interesting headline just scrolled out of view, you have also some ways to influence the scrolling:

- You can click on the news scroller with the left mouse button and move the mouse around (while holding the left mouse button pressed down). The news scroller will continue scrolling as usual if you release the left mouse button again.

- If you own a so-called Wheelmouse, you can use the wheel on your mouse to scroll the headlines back and forth.

There's also a very powerful context menu , which you can access either by clicking on the news scroller with the right mouse button, or by clicking on the arrow button with the left button. This context menu is the most interesting part of the applet, as it contains about all the functionality.

### The Context Menu

This is what the context menu of &knewsticker; looks like, if using just the default news sites.
This is what the context menu of &knewsticker; looks like, if using just the default news sites.

The context menu is basically split into two functional parts:

The upper part shows a list of entries, each entry having a small icon like this next to it. This list represents the list of currently configured news sites. You can click on any of the news sources to open another menu which contains a listing of headlines which are available for that particular news site as well as an entry labelled Check news to refresh the headline list for this news site. Each of the headlines has an icon next to it which indicates whether you have read that article already or the in case it is still unread.

The lower part shows currently four entries (explaining from top to bottom):

Check news

  This entry has a little next to it. If you want to force &knewsticker; to check the configured news sites for new articles, you can click here.

  This does not reset the internal timer which queries the news sites for new headlines automatically in certain intervals.

Offline mode

  This entry in the context menu has no icon associated to it. Click this button to enable a special offline mode which pauses the internal timer for querying the news sites and prevents any automatical download of new headlines. The offline mode comes in handy if you have to leave your computer for a while during which the system isn't connected to the Internet, as it saves you from all the error messages which pop up if any of the news sites couldn't be connected.

  You can still force a reload for single news sites as well as for all the news sites by selecting the respective Check news entry.

Help

  This entry is marked with a small . Clicking on this entry opens the &knewsticker; documentation (which you're reading in this moment) which details all the features and abilities of &knewsticker;.

About

  This entry is marked with a small , too. Selecting it opens a small dialog which lists the contributors of &knewsticker; as well as the copyright and the license.

Preferences

  This entry is easily recognizable due to the icon which is next to it. Select this entry to open the preferences dialog which lets you customize all of the properties for &knewsticker;

## Frequently Asked Questions

&reporting.bugs;

Where do I find the RDF file for the news site XY?

It's actually possible that the news site you're referring to doesn't provide any RDF or RSS file at all! Nevertheless you might want to check http://www.webreference.com/services/news for a more or less comprehensive list of sites on the web which provide a RDF or RSS file. Another great resource for RDF files is http://www.xmltree.com, where you can find hundreds of RDF and RSS files, sorted by language and/or topic.

If you found any interesting news sites which provide such a backend, though, don't hesitate to send them to Frerich Raabe raabe@kde.org so that they can be included in future releases. Thank you!

## Credits And License

&knewsticker;

Program copyright 2000, 2001 Frerich Raabe raabe@kde.org

Contributors:

- Malte Starostik malte.starostik@t-online.de

- Wilco Greven greven@linux.org

Documentation copyright 2001 Frerich Raabe raabe@kde.org

&underFDL; &underBSDLicense;

## Glossary

This chapter is intended to explain the various acronyms which have been used throughout the &knewsticker; documentation. If you feel any acronyms or terms are missing here, please don't hesitate to send an email to Frerich Raabe raabe@kde.org so that they can be added. Thank you.

RDF

  Resource Description Framework. A language derived from XML which describes metadata. Commonly used as a backend format for articles and other publications. For more detailed information on RDF files, you might want to read the brief info on RDF files, or go directly to the official page on RDF files at the World Wide Web Consortium.

RSS

  The RDF Site Summary is actually an extension to the RDF language. Quoting the official RSS v1.0 specification:

  RDF Site Summary (RSS) is a lightweight multipurpose extensible metadata description and syndication format. RSS is an XML application, conforms to the W3C's RDF Specification and is extensible via XML-namespace and/or RDF based modularization.

XML

  The Extensible Markup Language is the universal format for structured documents and data on the Web. It's a derivate of SGML which fits the need of the world wide web. You might want to check the the Extensible Markup Language page at the World Wide Web Consortium for further information.

W3C

  An abbreviation for World Wide Web Consortium Quoting the official homepage of the W3C, the World Wide Web Consortium (W3C) develops interoperable technologies (specifications, guidelines, software, and tools) to lead the Web to its full potential as a forum for information, commerce, communication, and collective understanding

&URL;

  &URL; stands for Uniforme Resource Locator, a specially formatted string which can reference resources like images, documents and other things on the Internet. Please refer to the respective webpage for more detailed information on this topic.

DCOP

  The Desktop COmmunication Protocol is a way for applications to communicate to each other. For instance, &knewsticker;'s configuration dialog uses DCOP to tell the applet itself about the current configuration. For more detailled information on DCOP you might want to visit http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html for a complete explanation of DCOP.

## Installation

### Where to get &knewsticker;

&knewsticker; is part of the &kde; Project . You will find the current version of &knewsticker; in the kdenetwork package at ftp://ftp.kde.org/pub/kde , the &FTP; server of the &kde; project.

### Requirements

If you want to install &knewsticker;, you need at least a &kde; 2.1 installation.

If you intend to compile and install &knewsticker; yourself, you have to make sure that the following programs are present on your system:

- g++ 2.8 / egcs 1.0.3 (or compatible)

- GNU make

- autoconf 2.1

- automake 1.4

- Qt 2.2.x

- KDE 2.1

### Compilation And Installation

&knewsticker; is part of the kdenetwork package of &kde; 2.1 and is installed together with it. In general, there is no need for the user to compile the sourcecode of &knewsticker; by hand. If you nevertheless intend to do so or if you have only the sourcecode available, compilation and installation is, as usual on Linux, done by typing:

    % ./configure
    % make
    % su -c "make install"

&knewsticker; uses autoconf and automake, so there shouldn't occur any problems during the compilation process. If you do hit on any problems though, please contact the &kde; developers mailing list kde-devel@master.kde.org.

## Information For Developers And Advanced Users

&knewsticker; features a currently rather limited but steadily growing DCOP interface. This is not only used to communicate with other applications, it makes it possible to control &knewsticker; with a shellscript as well. The more the interface is extended, the more useful it will become and the more flexible &knewsticker; will be controllable from a script.

To use these DCOP functions you can either use the dcop commandline program or use the more convenient KDCOP application. Both provide the same functionality so it's actually just a matter of taste which program you prefer. :-)

This chapter assumes that you're using the commandline program dcop. To access &knewsticker;'s DCOP functions make sure that &knewsticker; is started and then just enter something like this at the console:

    % dcop knewsticker KNewsTicker [function]

If an error appears that tells you that `dcop` couldn't be found or executed, please check whether the file `dcop` exists in `$KDEDIR/bin` and make sure it's permissions are appropriately set.

In that command line, just replace [function] with the respective function name, &ie; type

    % dcop knewsticker KNewsTicker updateNews

to make &knewsticker; check for new news and download them if neccessary.

### DCOP Reference

So, here's (finally) the complete list of all the DCOP which &knewsticker; provides:

`updateNews`

  This function forces &knewsticker; to updates the internal list of articles (&eg; it queries the list of news sources which has been configured for new news) and downloads them when neccessary.

  This also works if &knewsticker; is currently in offline mode.

  Example:

      % dcop knewsticker KNewsTicker updateNews

`reparseConfig`

  The `reparseConfig` command makes &knewsticker; reload it's configuration from the configuration file. This function is used by the configuration dialog to talk to &knewsticker; but you can use it in case you modified the configuration file by hand.

  The configuration file is saved in `~/.kde/share/config/knewstickerrc`

  Example:

      % dcop knewsticker KNewsTicker reparseConfig

`setOfflineMode [bool]`

  You can call this function to define whether &knewsticker; is currently in the offline mode (&eg; whether &knewsticker; should query the configured news sites for new news).

  Example:

      % dcop knewsticker KNewsTicker setOfflineMode true

  to enable the offline mode, or type

      % dcop knewsticker KNewsTicker setOfflineMode false

  to disable offline mode.

&documentation.index;