You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1400 lines
54 KiB
1400 lines
54 KiB
<?xml version="1.0" ?>
|
|
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
|
<!ENTITY kappname "&knewsticker;">
|
|
<!ENTITY package "tdenetwork">
|
|
<!ENTITY % addindex "IGNORE">
|
|
<!ENTITY % English "INCLUDE">
|
|
<!ENTITY RSS "<acronym>RSS</acronym>">
|
|
]>
|
|
|
|
<book lang="&language;">
|
|
|
|
<bookinfo>
|
|
<title>The &knewsticker; Handbook</title>
|
|
|
|
<authorgroup>
|
|
<author>&Frerich.Raabe; &Frerich.Raabe.mail;</author>
|
|
<othercredit role="reviewer">&Jonathan.Singer; &Jonathan.Singer.mail;</othercredit>
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
</authorgroup>
|
|
|
|
<copyright>
|
|
<year>2001, 2002, 2003</year>
|
|
<holder>&Frerich.Raabe;</holder>
|
|
</copyright>
|
|
|
|
<legalnotice>&FDLNotice;</legalnotice>
|
|
|
|
<date>2003-10-14</date>
|
|
<releaseinfo>2.00.00</releaseinfo>
|
|
|
|
<abstract>
|
|
<para>&knewsticker; is a news ticker applet for the &kde; panel (also
|
|
known as &kicker;).</para>
|
|
</abstract>
|
|
|
|
<keywordset>
|
|
<keyword>KDE</keyword>
|
|
<keyword>KNewsTicker</keyword>
|
|
<keyword>tdenetwork</keyword>
|
|
<keyword>news ticker</keyword>
|
|
<keyword>applet</keyword>
|
|
</keywordset>
|
|
</bookinfo>
|
|
|
|
<chapter id="introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>&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 <ulink url="http://slashdot.org">Slashdot</ulink>,
|
|
<ulink url="http://lwn.net">&Linux; Weekly News</ulink> or
|
|
<ulink url="http://freshmeat.net">Freshmeat</ulink>).</para>
|
|
|
|
<para>To achieve this, &knewsticker; requires the news sites to provide a
|
|
special &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.</para>
|
|
|
|
<sect1 id="rssfiles">
|
|
<title>Brief Info On &RSS; Files</title>
|
|
|
|
<para>&RSS; 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 &RSS; files? This section tries to give
|
|
a brief answer to this question, as well as pointers to other sources for
|
|
further reference.</para>
|
|
|
|
<para>The short answer: &RSS; is an
|
|
<acronym>&XML;-based</acronym> format for syndicating web content.</para>
|
|
|
|
<para>&RSS; is often used as an acronym for <quote>Rich Site
|
|
Summary</quote> – that's not a common definition but it gives an idea on what
|
|
the creators of &RSS; had in mind. There is no consensus on
|
|
what &RSS; stands for, so it's actually not an acronym, it's a
|
|
name.</para>
|
|
|
|
<para>&RSS; originated in 1999 and was invented by
|
|
<ulink url="http://www.netscape.com">NetScape</ulink> as a syndication format
|
|
for their <ulink url="http://my.netscape.com">my.netscape.com</ulink> website;
|
|
this very first &RSS; release was version 0.9. A few months
|
|
after that, &Netscape; introduced &RSS; version 0.91, which
|
|
incorporated many features of the <quote><scriptingNews></quote>
|
|
format.</para>
|
|
|
|
<para>The basic concept of all &RSS; files is to provide a
|
|
clean, simple and portable way to distribute web content, in particular news:
|
|
the news sites provide an &RSS; file which basically contains
|
|
a set of records, and each record consists of a headline and a
|
|
&URL; which points to the complete article. The
|
|
&RSS; file also contains other general information about the
|
|
particular news site, such as its name and the homepage, which is evaluated
|
|
by &knewsticker;.</para>
|
|
|
|
<para>Nowadays there are a few additional, more sophisticated versions of the
|
|
&RSS; format
|
|
(<ulink url="http://backend.userland.com/rss091">0.91</ulink>,
|
|
<ulink url="http://backend.userland.com/rss092">0.92</ulink>,
|
|
<ulink url="http://backend.userland.com/rss093">0.93</ulink>,
|
|
<ulink url="http://web.resource.org/rss/1.0/">1.0</ulink> and the current
|
|
format version
|
|
<ulink url="http://backend.userland.com/rss">2.0</ulink>) but the first two
|
|
versions still make up about 85% of the files provided on the web. Nevertheless,
|
|
all versions up to 2.0 can be processed with &knewsticker;!</para>
|
|
|
|
<para>Of course, this is only a short and highly incomplete attempt at
|
|
explaining the basic ideas behind &RSS; files. 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:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.webreference.com/authoring/languages/xml/rss/intro/">http://www.webreference.com/authoring/languages/xml/rss/intro/</ulink></term>
|
|
<listitem><para>A very pragmatic introduction to the &RSS;
|
|
format, with concrete examples and guidelines. Together with the
|
|
authoritative specifications, this makes a good guide for people
|
|
who are thinking
|
|
about providing an &RSS; newsfeed on their home
|
|
page.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oreillynet.com/rss/">http://www.oreillynet.com/rss/</ulink></term>
|
|
<listitem><para>The &RSS; page from O'Reilly features a
|
|
lot of general articles about employing and using &RSS; files,
|
|
up to date news about the &RSS; development community as well
|
|
as vital information for web developers who are considering taking advantage of
|
|
&RSS;.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><ulink url="http://blogspace.com/rss/">http://blogspace.com/rss/</ulink></term>
|
|
<listitem><para>This page is another excellent source of news about the
|
|
&RSS; development, which is especially interesting to
|
|
developers working with &RSS;-based technology.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.w3.org/RDF/">http://www.w3.org/RDF/</ulink></term>
|
|
<listitem><para><emphasis>The</emphasis> authoritative source about
|
|
<acronym>RDF</acronym>, an &XML;-based language from which
|
|
modern &RSS; versions are derived, published by the
|
|
<ulink url="http://www.w3.org">World Wide Web Consortium</ulink>. It features
|
|
a comprehensive list of links to other sites on the topic as well as a timeline
|
|
of the <acronym>RDF</acronym> development, an overview over the architecture, an
|
|
archive with articles about <acronym>RDF</acronym> as well as a carefully
|
|
assembled list of tools for developers who intend to work with
|
|
<acronym>RDF</acronym>.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>Developers will also want to check the authoritative specifications for
|
|
the various &RSS; versions:</para>
|
|
|
|
<orderedlist>
|
|
<title>&RSS; Specifications</title>
|
|
<listitem><para>
|
|
Version 0.90: <ulink url="http://www.purplepages.ie/rss/netscape/rss0.90.html">http://www.purplepages.ie/rss/netscape/rss0.90.html</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Version 0.91: <ulink url="http://backend.userland.com/rss091">http://backend.userland.com/rss091</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Version 0.92: <ulink url="http://backend.userland.com/rss092">http://backend.userland.com/rss092</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Version 0.93: <ulink url="http://backend.userland.com/rss093">http://backend.userland.com/rss093</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Version 1.0: <ulink url="http://web.resource.org/rss/1.0/">http://web.resource.org/rss/1.0/</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Version 2.0: <ulink url="http://backend.userland.com/rss">http://backend.userland.com/rss</ulink>
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>If you find any other sites or documents on this topic, and think they are
|
|
worth being mentioned here, don't hesitate to send them to &Frerich.Raabe;
|
|
&Frerich.Raabe.mail; so that they can be included in this document and
|
|
help everybody.</para>
|
|
|
|
<para>Thank you very much!</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="starting-knewsticker">
|
|
<title>Starting &knewsticker;</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>Here is a screenshot of &knewsticker; in &kde;'s
|
|
panel.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="knewsticker-kicker.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>Here is a screenshot of &knewsticker; in &kde;'s
|
|
panel.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>
|
|
&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 right-click
|
|
on the &kde; panel and choose <menuchoice><guimenu>Add</guimenu>
|
|
<guisubmenu>Applet</guisubmenu><guimenuitem>&knewsticker;</guimenuitem>
|
|
</menuchoice>.</para>
|
|
|
|
<screenshot>
|
|
<screeninfo>Here is a screenshot of &knewsticker; in its own child
|
|
panel.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="knewsticker-childpanel.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>Here is a screenshot of &knewsticker; in its own child
|
|
panel.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>Another good way to use &knewsticker; is to put it into its own child
|
|
panel. Just add a new child panel by choosing <menuchoice><guimenu>Add</guimenu>
|
|
<guisubmenu>Extension</guisubmenu><guimenuitem>Child Panel</guimenuitem>
|
|
</menuchoice> from the panel menu;. Now you can simply right-click on the child
|
|
panel and select &knewsticker; as described above.</para>
|
|
|
|
<screenshot>
|
|
<screeninfo>Here is a screenshot of &knewsticker; in its own
|
|
window.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="knewsticker-ownwindow.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>Here is a screenshot of &knewsticker; in its own
|
|
window.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>A third, popular, way to run &knewsticker; is by selecting <menuchoice>
|
|
<guimenu>Internet</guimenu><guimenuitem>&knewsticker; (News
|
|
Ticker)</guimenuitem></menuchoice> from the <guilabel>K</guilabel> menu. This
|
|
will start &knewsticker; and make it run in its own window which you can then
|
|
resize and move around as you wish.</para>
|
|
</chapter>
|
|
|
|
<chapter id="configuration">
|
|
<title>Configuring &knewsticker;</title>
|
|
|
|
<para>You can access &knewsticker;'s configuration dialog by right-clicking
|
|
onto the scroll text, or by clicking on the button with the arrow on it and
|
|
choosing the entry labelled <guimenuitem><inlinemediaobject><imageobject>
|
|
<imagedata fileref="preferences-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> Preferences</guimenuitem> in the menu.</para>
|
|
|
|
<sect1 id="config-general">
|
|
<title>General Options</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the <guilabel>General</guilabel> tab of the
|
|
preferences dialog looks like.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="kcmnewsticker-general.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the <guilabel>General</guilabel> tab of the
|
|
preferences dialog looks like.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>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:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Mousewheel sensitivity:</guilabel></term>
|
|
<listitem>
|
|
<para>This slider allows you to define how fast/slow the text should be
|
|
scrolled when using the mousewheel.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>News query interval</guilabel></term>
|
|
<listitem>
|
|
<para>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:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>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
|
|
<ulink url="http://slashdot.org">Slashdot</ulink> or
|
|
<ulink url="http://freshmeat.net">Freshmeat</ulink>) as they
|
|
have generally already enough work with processing the incoming
|
|
queries.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A higher value (higher than 45 minutes) won't make you
|
|
hear about news that quick. For non-time-critical 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.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<tip><para>The default value (30 minutes) should be appropriate and
|
|
reasonable in most cases.</para></tip>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Use custom names for news sites</guilabel></term>
|
|
<listitem>
|
|
<para>Check this box to make the news ticker use the names you
|
|
specified in the list of news sources (available on the tab
|
|
labeled <guilabel>News sources</guilabel>) instead of the ones
|
|
the news sites themselves report. This can be handy for news sites
|
|
which report a very long or useless name.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="config-newssources">
|
|
<title>Configuration of the news sources</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the <guilabel>News Sources</guilabel> tab of the
|
|
preferences dialog looks like.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="kcmnewsticker-newssources.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the <guilabel>News Sources</guilabel> tab of
|
|
the preferences dialog looks like.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>On this tab you can 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. At the bottom of the page you can also find three buttons which have
|
|
the same effect.</para>
|
|
|
|
<sect2>
|
|
<title>Adding a news site</title>
|
|
<para>There are four ways to <emphasis>add</emphasis> a new news site to the
|
|
list:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You can click on the button at the bottom labeled
|
|
<guilabel>Add...</guilabel>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can click with the right mouse button on the table and choose
|
|
<guimenuitem>Add news source</guimenuitem>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can drag any &RSS; file from another
|
|
application (such as &konqueror;) onto the table. This adds a new entry
|
|
to the list, sets the name to <quote>Unknown</quote> and sets the
|
|
maximum number of articles to 10.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>And finally, you can just click on any &RSS;
|
|
file in the &konqueror; filemanager to have it added to the list
|
|
immediately.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Either way will cause the <link linkend="config-news-site-dialog">News site
|
|
dialog</link> to show up, presenting you with a form to enter the properties of
|
|
the news site to add.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Modifying an existing news site</title>
|
|
<para>There are two ways to adjust the properties of an existing news
|
|
site:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You can click on the button at the bottom labeled
|
|
<guilabel>Modify...</guilabel>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can right-click with the right mouse button on the news site
|
|
you'd like to edit and choose <guimenuitem>Modify '...'</guimenuitem>
|
|
from the menu.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>No matter which way you chose, it will cause the
|
|
<link linkend="config-news-site-dialog">News site dialog</link> to pop up,
|
|
showing the properties of the selected news site.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Removing a news site</title>
|
|
<para>Of course, you want to <emphasis>remove</emphasis> a news source from
|
|
the list sometimes. To do this, you can either</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>click on the button at the bottom labeled
|
|
<guilabel>Remove</guilabel>, or</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>right-click with the right mouse button on the news site
|
|
you'd like to edit and choose <guimenuitem>Remove '...'</guimenuitem>
|
|
from the menu.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>In both cases, a confirmation box will pop up and make sure you didn't
|
|
select the wrong entry.</para>
|
|
<tip><para>You can also remove multiple news sites at once by holding &Ctrl;
|
|
while clicking on the entries you wouldd like to remove, or by clicking the
|
|
<mousebutton>left</mousebutton> mousebutton and dragging the mouse over all
|
|
the entries you'd like to select.</para></tip>
|
|
</sect2>
|
|
|
|
<sect2 id="config-news-site-dialog">
|
|
<title>The news site dialog</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the dialog for adding and editing news sites looks
|
|
like.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="kcmnewsticker-newssitedialog.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the dialog for adding and editing news sites
|
|
looks like.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>When adding or modifying a news site, the news site dialog (shown above)
|
|
pops up and provides input facilities to edit the various properties of a news
|
|
site:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Name:</guilabel></term>
|
|
<listitem>
|
|
<para>This is the name of the news source.</para>
|
|
<note><para>This text will only be used if <guilabel>Use custom names
|
|
for news sites</guilabel> on the tab labeled
|
|
<link linkend="config-general">General</link> is
|
|
activated.</para></note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Source file:</guilabel></term>
|
|
<listitem>
|
|
<para>Here you can set the &URL; which references
|
|
the &RSS; file of this news site; this can either
|
|
be a local file, or a file saved on a remote server. You can also
|
|
click on the button at the right to open a convenient file-selection
|
|
dialog and browse to the file you would like to use, instead of typing
|
|
the &URL; by hand.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>The file is a program</guilabel></term>
|
|
<listitem>
|
|
<para>If this file is checked, &knewsticker; will not assume that the
|
|
&URL; (which was specified in the <guilabel>Source
|
|
file</guilabel> field) references an &RSS; file, but
|
|
rather that the &URL; refers a program (usually a
|
|
script). When querying this news site, &knewsticker; will execute the
|
|
program and treat whatever the program prints to stdout as
|
|
&RSS; markup. This is very convenient for conversion
|
|
scripts which download an &HTML; file and process it,
|
|
producing &RSS; markup which is suitable for use with
|
|
&knewsticker;.</para>
|
|
<tip><para>You can find some scripts which ⪚ download stock data in
|
|
the tdeaddons module, in the
|
|
<filename class="directory">knewsticker-scripts</filename>
|
|
directory.</para></tip>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Category:</guilabel></term>
|
|
<listitem>
|
|
<para>Here you can specify into which category the news site belongs.
|
|
Arranging the news sites into categories makes it much easier to
|
|
maintain large lists of news sites.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Max. articles:</guilabel></term>
|
|
<listitem>
|
|
<para>This option lets you define how many articles &knewsticker; will
|
|
cache for this news site; the value will never be exceeded.</para>
|
|
<para>This is particularly handy for news sites which provide only
|
|
three news items at once, but you'd like to see the last ten items (for
|
|
instance); &knewsticker; will always download the three items and merge
|
|
them into its list, caching the last seven items.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Icon:</guilabel></term>
|
|
<listitem>
|
|
<para>Here you can specify a &URL; to an image file
|
|
(preferably 16x16 pixels in size) which should be used for this news
|
|
site. Icons make it much easier to distinguish multiple news sites, and
|
|
see which news site a headline appeared on as it scrolls by in
|
|
&knewsticker;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>At the button you will find the usual buttons. One of them deserves an
|
|
extra note: clicking on the <guilabel>Suggest</guilabel> button will make
|
|
&knewsticker; try to guess suitable values for most of the fields if you
|
|
specify a &URL; to a valid source file.</para>
|
|
|
|
<para>This means that you can usually just paste a &URL; to
|
|
an &RSS; file in the input field labeled <guilabel>Source
|
|
file</guilabel>, press the <guilabel>Suggest</guilabel> button and then modify
|
|
the suggested values as needed.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="config-filters">
|
|
<title>Filters</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the <guilabel>Filters</guilabel> tab of the
|
|
preferences dialog looks like.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="kcmnewsticker-filters.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the <guilabel>Filters</guilabel> tab of
|
|
the preferences dialog looks like.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>This tab allows you to define various filters which should be applied
|
|
before showing the headlines in the scroll text.</para>
|
|
|
|
<note><para>These filters only affect the headlines which are shown in the
|
|
scrolltext; the menu will always show all of the headlines.</para></note>
|
|
<para>The major part of the tab is occupied by a table which lists the
|
|
currently configured filters. Each filter has a small checkable box - checking
|
|
that box enables the filter, unchecking it temporarily disables it without
|
|
removing it from the list.</para>
|
|
|
|
<para>By default there are no filters, so chances are that the table is
|
|
completely empty for you. Of course, this dialog provides you with ways
|
|
to add new filters, and manage them in general:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>To <emphasis>add</emphasis> a filter, simply enter the filter
|
|
properties (see <link linkend="filter-components">Filter
|
|
Components</link> for a detailed description of the various filter
|
|
properties) using the input fields in the box labeled <guilabel>Filter
|
|
properties</guilabel> and then press the button labeled
|
|
<guilabel>Add</guilabel>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>To <emphasis>modify</emphasis> an existing filter, select the
|
|
filter you would like to edit in the table by left-clicking on it and
|
|
then change its properties in the box at the bottom.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>To <emphasis>remove</emphasis> a filter, select it in the table
|
|
and then press the button labeled <guilabel>Remove</guilabel>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<sect2 id="filter-components">
|
|
<title>Filter Components</title>
|
|
|
|
<para>Each filter consists of four components:</para>
|
|
|
|
<orderedlist>
|
|
<title>Filter Components</title>
|
|
<listitem>
|
|
<para>Action – this can be either <guilabel>Show</guilabel> or
|
|
<guilabel>Hide</guilabel> and defines what should happen to a headline
|
|
in case this filter matches.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>News sources – here you can define whether the filter affects only
|
|
single news sources, or whether this filter should be applied to the
|
|
headlines of all news sources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Condition – this is a verb which defines, together with the
|
|
Expression, whether a filter matches. A condition can be ⪚
|
|
<guilabel>contains</guilabel>, <guilabel>doesn't equal</guilabel> or
|
|
<guilabel>matches</guilabel>. See below for a more detailed
|
|
description.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Expression - this is a user-defined string which forms the body
|
|
of the filter, together with the Condition. See below for a more detailed
|
|
description of this component.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>All these components can be configured using the facilities in the frame
|
|
labeled <guilabel>Filter properties</guilabel>. The possible states of the
|
|
Condition component deserve a special explanation:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><guilabel>contains</guilabel>, <guilabel>doesn't contain</guilabel>:
|
|
this filter matches if the headline contains / doesn't contain the
|
|
specified expression.</para>
|
|
<note><para>The expression isn't treated case-sensitively, so the expressions
|
|
<quote>KDE</quote>, <quote>kDE</quote> or <quote>kde</quote> will all match
|
|
headlines which contain <quote>KDE</quote>.</para></note>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>equals</guilabel>, <guilabel>doesn't equal</guilabel>:
|
|
this filter matches if the headline equals / doesn't equal the
|
|
specified expression.</para>
|
|
<note><para>The expression is treated case-sensitively, so of the expressions
|
|
<quote>&Linux;</quote>, <quote>linux</quote> or <quote>LINUX</quote>, only the
|
|
first will match <quote>&Linux;</quote>.</para></note>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>matches</guilabel>: using this condition will make
|
|
&knewsticker; treat the given expression as a <quote>regular
|
|
expression</quote>. For further information on regular expressions you
|
|
might want to read
|
|
<ulink url="http://www.evolt.org/article/rating/20/22700/">this
|
|
article</ulink> which was published at
|
|
<ulink url="http://www.evolt.org">www.evolt.org</ulink>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="config-scroller">
|
|
<title>Scroller Preferences</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the <guilabel>Scroller Preferences</guilabel> tab
|
|
of the preferences dialog looks like.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="kcmnewsticker-scrollerprefs.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the <guilabel>Scroller Preferences</guilabel>
|
|
tab of the preferences dialog looks like.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>This tab lets you define various options which affect &knewsticker;'s
|
|
scroll text:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Scrolling speed</guilabel></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Direction of scrolling</guilabel></term>
|
|
<listitem>
|
|
<para>These options allow you to define in what direction the text
|
|
should be scrolled, ⪚ to the left or to the right, upwards or
|
|
downwards. You can also rotate the text by 90 or 270 degrees here,
|
|
which is not exactly readable but it makes sense for vertically
|
|
aligned panels.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Scrolltext font</guilabel></term>
|
|
<listitem>
|
|
<para>Click on the button at the right labeled <guilabel>Choose
|
|
Font...</guilabel> to choose the font which will be used for the
|
|
scrolling text.</para>
|
|
<tip><para>Certain fonts are harder to read than others, especially
|
|
when they are used for a scrolltext, so you should probably choose a font
|
|
which can even easily be read if it's moving.</para></tip>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Foreground color</guilabel></term>
|
|
<listitem>
|
|
<para>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 (&ie; the color of the text itself).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Background color</guilabel></term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Highlighted color</guilabel></term>
|
|
<listitem>
|
|
<para>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).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Scroll the most recent headlines only</guilabel></term>
|
|
<listitem>
|
|
<para>Check this button to make the scrolltext show just the most
|
|
recent headline for each news site, instead of showing every
|
|
headline available from every news site.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Show icons</guilabel></term>
|
|
<listitem>
|
|
<para>Checking this box will make &knewsticker; show an icon (if
|
|
available) in front of each headline which is scrolled along; this
|
|
makes determining which news site provided each headline much
|
|
easier.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Temporarily slowed scrolling</guilabel></term>
|
|
<listitem>
|
|
<para>Check this box to make &knewsticker; slow the scrolling down
|
|
when you move the mouse cursor over the scrolling text. This makes
|
|
clicking on items and dragging away the icons (if enabled) a lot
|
|
easier.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Underline highlighted headline</guilabel></term>
|
|
<listitem>
|
|
<para>Check this box to have the currently highlighted headline
|
|
(&ie; the headline which is currently under the mouse cursor)
|
|
underlined.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="using-knewsticker">
|
|
<title>Using &knewsticker;</title>
|
|
|
|
<para>Using &knewsticker; is fairly straightforward and should give you no
|
|
big problems, assuming that you have already
|
|
<link linkend="configuration">configured it</link>. No matter
|
|
whether you are running &knewsticker; in the main panel, in its own child
|
|
panel or in its own window, it appears as an area with a scrolling text and
|
|
a button with a small arrow next to it.</para>
|
|
|
|
<sect1 id="applet-descr">
|
|
<title>The Main Interface</title>
|
|
|
|
<para>The area (it is white by default, but you can change the background
|
|
color easily using the preferences dialog) with the scrolling text in it is
|
|
called the <quote>news scroller</quote>. 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 some ways to influence the
|
|
scrolling:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You can click on the news scroller with the
|
|
<mousebutton>left</mousebutton> mouse button and move the mouse around
|
|
(while holding the <mousebutton>left</mousebutton> mouse button pressed
|
|
down). The news scroller will continue scrolling as usual if you release
|
|
the left mouse button again.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you own a so-called <quote>wheel mouse</quote>, you can use
|
|
the wheel on your mouse to scroll the headlines back and forth.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>There's also a very powerful <link linkend="contextmenu-descr">context
|
|
menu</link>, which you can access either by clicking on the news scroller with
|
|
the <mousebutton>right</mousebutton> mouse button, or by clicking on the
|
|
arrow button with the <mousebutton>left</mousebutton> button. This context menu
|
|
is the most interesting part of the applet, as it contains about all the
|
|
functionality.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="contextmenu-descr">
|
|
<title>The Context Menu</title>
|
|
|
|
<screenshot>
|
|
<screeninfo>This is what the context menu of &knewsticker; looks like, when
|
|
using just the default news sites.</screeninfo>
|
|
<mediaobject>
|
|
<imageobject><imagedata fileref="contextmenu.png" format="PNG"/></imageobject>
|
|
<textobject>
|
|
<phrase>This is what the context menu of &knewsticker; looks like,
|
|
when using just the default news sites.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<para>The context menu is basically split into two functional parts:</para>
|
|
|
|
<para>The upper part shows a list of entries, each entry having a small icon like
|
|
this <inlinemediaobject><imageobject>
|
|
<imagedata fileref="newssite-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> 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 labeled <guilabel>
|
|
<inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png"
|
|
format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel> to
|
|
refresh the headline list for this news site. Each of the headlines has an
|
|
<inlinemediaobject><imageobject>
|
|
<imagedata fileref="oldarticle-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> icon next to it indicating that that you
|
|
have read that article already or the <inlinemediaobject><imageobject>
|
|
<imagedata fileref="newarticle-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> if it is still
|
|
unread.</para>
|
|
|
|
<para>The lower part currently shows five entries (explained from top to
|
|
bottom):</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png" format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel></term>
|
|
<listitem>
|
|
<para>This entry has a little <inlinemediaobject><imageobject>
|
|
<imagedata fileref="checknews-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> next to it. If you want to force &knewsticker;
|
|
to check the configured news sites for new articles, you can click
|
|
here.</para>
|
|
<note><para>This does not reset the internal timer which queries the
|
|
news sites for new headlines automatically in certain
|
|
intervals.</para></note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Offline mode</guilabel></term>
|
|
<listitem>
|
|
<para>This entry in the context menu has no icon associated with it.
|
|
Click this button to enable a special <quote>offline mode</quote>
|
|
which pauses the internal timer for querying the news sites and
|
|
prevents any automatic 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.</para>
|
|
<tip><para>You can still force a reload for single news sites as
|
|
well as for all the news sites by selecting the respective
|
|
<guilabel><inlinemediaobject><imageobject><imagedata
|
|
fileref="checknews-icon.png" format="PNG"/></imageobject>
|
|
</inlinemediaobject> Check news</guilabel> entry.</para></tip>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="help-icon.png" format="PNG"/></imageobject></inlinemediaobject> Help</guilabel></term>
|
|
<listitem>
|
|
<para>This entry is marked with a small <inlinemediaobject>
|
|
<imageobject><imagedata fileref="help-icon.png" format="PNG"/>
|
|
</imageobject></inlinemediaobject>. Clicking on this entry opens
|
|
the &knewsticker; documentation (which you're reading in this
|
|
moment) which details all the features and abilities of
|
|
&knewsticker;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/></imageobject></inlinemediaobject> About</guilabel></term>
|
|
<listitem>
|
|
<para>This entry is marked with a small <inlinemediaobject>
|
|
<imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/>
|
|
</imageobject></inlinemediaobject>. Clicking on this entry opens
|
|
a small dialog showing who's to blame for &knewsticker; and credits
|
|
people who contributed significant enhancements for
|
|
it.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="preferences-icon.png" format="PNG"/></imageobject></inlinemediaobject> Preferences</guilabel></term>
|
|
<listitem>
|
|
<para>This entry is easily recognizable due to the <inlinemediaobject>
|
|
<imageobject><imagedata fileref="preferences-icon.png" format="PNG"/>
|
|
</imageobject></inlinemediaobject> icon which is next to it. Select
|
|
this entry to open the <link linkend="configuration">preferences
|
|
dialog</link> which lets you customize all of the properties of
|
|
&knewsticker;</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="faq">
|
|
<title>Frequently Asked Questions</title>
|
|
|
|
&reporting.bugs;
|
|
|
|
<qandaset id="faqlist">
|
|
<qandaentry>
|
|
<question>
|
|
<para>Where do I find the &RSS; file for the news
|
|
site XYZ?</para>
|
|
</question>
|
|
<answer>
|
|
<para>It's possible that the news site you're referring to
|
|
doesn't provide any &RSS; file at all! Here's a short list of
|
|
websites which provide thousands of &RSS; feeds, sorted by
|
|
language and/or topic - for free:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<ulink url="http://www.webreference.com/services/news">WebReference.com</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<ulink url="http://www.newsisfree.com/syndicate.php">NewsIsFree</ulink>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<ulink url="http://w.moreover.com/categories/category_list_rss.html">MoreOver</ulink>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>If you have found any interesting news sites which provide
|
|
such a backend, don't hesitate to send them to &Frerich.Raabe;
|
|
&Frerich.Raabe.mail; so that they can be included in
|
|
future releases. Thank you!</para>
|
|
</answer>
|
|
</qandaentry>
|
|
<qandaentry>
|
|
<question>
|
|
<para>How can I make &knewsticker; open articles in another browser
|
|
(⪚ Mozilla)?</para>
|
|
</question>
|
|
<answer>
|
|
<para>&knewsticker; will use whatever browser you have associated with
|
|
the text/html &MIME; type; the default browser used for viewing
|
|
&HTML; pages is &konqueror;.</para>
|
|
<para>You can find the dialog for changing this association by opening
|
|
the &kde; control center and browsing to <menuchoice><guimenu>KDE
|
|
Components</guimenu> <guisubmenu>File
|
|
Associations</guisubmenu></menuchoice>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
</chapter>
|
|
|
|
<chapter id="credits">
|
|
<title>Credits And License</title>
|
|
|
|
<para>&knewsticker;</para>
|
|
|
|
<para>Program copyright 2000, 2001, 2002, 2003 &Frerich.Raabe;
|
|
&Frerich.Raabe.mail;</para>
|
|
|
|
<para>Contributors:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Malte Starostik <email>malte.starostik@t-online.de</email></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&Wilco.Greven; &Wilco.Greven.mail;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Adriaan de Groot <email>adrig@sci.kun.nl</email></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Documentation copyright 2001, 2002, 2003 &Frerich.Raabe;
|
|
&Frerich.Raabe.mail;</para>
|
|
|
|
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
|
&underFDL;
|
|
&underBSDLicense;
|
|
</chapter>
|
|
|
|
<glossary id="glossary">
|
|
<title>Glossary</title>
|
|
|
|
<para>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;
|
|
&Frerich.Raabe.mail; so that they can be added. Thank you!</para>
|
|
|
|
<glossentry id="gloss-rdf">
|
|
<glossterm>RDF</glossterm>
|
|
<glossdef>
|
|
<para>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 <acronym>RDF</acronym> files, you might want to go
|
|
directly to the <ulink url="http://www.w3.org/RDF/">official page on
|
|
<acronym>RDF</acronym> files</ulink> at the
|
|
<ulink url="http://www.w3.org">World Wide Web
|
|
Consortium</ulink>.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="gloss-rss">
|
|
<glossterm>&RSS;</glossterm>
|
|
<glossdef>
|
|
<para>The <acronym>RDF</acronym> Site Summary is actually an
|
|
extension to the <acronym>RDF</acronym> language. Quoting the official
|
|
<ulink url="http://www.purl.org/rss/1.0/">&RSS; v1.0
|
|
specification</ulink>:</para>
|
|
<para><quote><acronym>RDF</acronym> Site Summary
|
|
(&RSS;) is a lightweight multipurpose extensible
|
|
metadata description and syndication format. &RSS; is
|
|
an &XML; application, conforms to the
|
|
<acronym>W3C</acronym>'s <acronym>RDF</acronym> specification and is
|
|
extensible via &XML;-namespace and/or
|
|
<acronym>RDF</acronym> based modularization.</quote></para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="gloss-xml">
|
|
<glossterm>&XML;</glossterm>
|
|
<glossdef>
|
|
<para>The Extensible Markup Language is the <quote>universal format
|
|
for structured documents and data on the Web</quote>. It's a derivative of
|
|
<acronym>SGML</acronym> which fits the needs of the world wide web. You
|
|
might want to check the the
|
|
<ulink url="http://www.w3.org/XML/">Extensible Markup Language</ulink>
|
|
page at the <ulink url="http://www.w3.org">World Wide Web
|
|
Consortium</ulink> for further information.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="gloss-w3c">
|
|
<glossterm>W3C</glossterm>
|
|
<glossdef>
|
|
<para>An abbreviation for <quote>World Wide Web Consortium</quote>.
|
|
Quoting the <ulink url="http://www.w3.org">official homepage</ulink> of
|
|
the <acronym>W3C</acronym>, <quote>the World Wide Web Consortium
|
|
(<acronym>W3C</acronym>) 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</quote></para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="gloss-url">
|
|
<glossterm>&URL;</glossterm>
|
|
<glossdef>
|
|
<para>&URL; stands for <quote>Uniform Resource Locator</quote>,
|
|
a specially formatted string which can reference resources like images,
|
|
documents and other things on the Internet. Please refer to the
|
|
corresponding <ulink url="http://www.w3.org/Addressing/">webpage</ulink>
|
|
for more detailed information on this topic.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="gloss-dcop">
|
|
<glossterm>&DCOP;</glossterm>
|
|
<glossdef>
|
|
<para>The Desktop COmmunication Protocol is a way for applications
|
|
to communicate to each other. For instance, &knewsticker;'s
|
|
<link linkend="configuration">configuration dialog</link> uses
|
|
&DCOP; to tell the applet itself about the current
|
|
configuration.</para>
|
|
<para>&knewsticker; provides an extensive
|
|
<link linkend="develinfo">&DCOP; interface</link>,
|
|
which makes it possible to control many of &knewsticker;'s functions
|
|
from the commandline.</para>
|
|
<para>For more detailled information on &DCOP;
|
|
you might want to visit
|
|
<ulink url="http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html">http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html</ulink>
|
|
for a complete explanation.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
</glossary>
|
|
|
|
<appendix id="develinfo">
|
|
<title>Information For Developers And Advanced Users</title>
|
|
|
|
<para>&knewsticker; features a currently rather extensive, and steadily growing
|
|
&DCOP; interface. This is not only used to communicate with
|
|
other applications, it makes it possible to control &knewsticker; with a
|
|
shell script 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.</para>
|
|
|
|
<para>To use these &DCOP; functions you can either use the
|
|
<application>dcop</application> commandline program or use the more convenient
|
|
<application>KDCOP</application> application. Both provide the same
|
|
functionality so it's actually just a matter of taste which program you prefer.
|
|
:-)</para>
|
|
|
|
<para>This chapter assumes that you're using the commandline program
|
|
<application>dcop</application>. To access &knewsticker;'s
|
|
&DCOP; functions make sure that &knewsticker; is <link
|
|
linkend="starting-knewsticker">started</link> and then just enter something like
|
|
this at the console:</para>
|
|
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>[function]</option></userinput>
|
|
</screen>
|
|
|
|
<note><para>If an error appears that tells you that <filename>dcop</filename>
|
|
couldn't be found or executed, please check whether the file
|
|
<filename>dcop</filename> exists in
|
|
<filename class="directory">$<envar>TDEDIR</envar>/bin</filename> and make sure its
|
|
permissions are set appropriately.</para></note>
|
|
|
|
<para>In that command line, just replace <quote>[function]</quote> with the
|
|
appropriate function name, &ie; type</para>
|
|
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
|
|
</screen>
|
|
|
|
<para>to make &knewsticker; check for new news items and download them if
|
|
necessary.</para>
|
|
|
|
<sect1 id="dcop-reference">
|
|
<title>&DCOP; Reference</title>
|
|
|
|
<para>In this section, all methods which are accessible via &knewsticker;'s
|
|
&DCOP; interface are listed.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><command>updateNews</command></term>
|
|
<listitem>
|
|
<para>This function forces &knewsticker; to update the internal list
|
|
of articles (&ie; it queries the list of news sources which has been
|
|
<link linkend="config-newssources">configured</link> for new news) and
|
|
downloads them when necessary.</para>
|
|
<note><para>This also works if &knewsticker; is currently in offline
|
|
mode.</para></note>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>reparseConfig</command></term>
|
|
<listitem>
|
|
<para>The <command>reparseConfig</command> command makes &knewsticker;
|
|
reload its configuration from the configuration file. This function is
|
|
used by the <link linkend="configuration">configuration dialog</link>
|
|
to talk to &knewsticker; but you can use it if you modified the
|
|
configuration file by hand.</para>
|
|
<tip><para>The configuration file is saved in
|
|
<filename>~/.trinity/share/config/knewsticker_appletrc</filename></para></tip>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>reparseConfig</option></userinput>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>setOfflineMode [bool]</command></term>
|
|
<listitem>
|
|
<para>You can call this function to define whether &knewsticker; is
|
|
currently in the offline mode (&ie; whether &knewsticker; should query
|
|
the <link linkend="config-newssources">configured news sites</link> for
|
|
new news).</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>true</option></userinput>
|
|
</screen>
|
|
<para>to enable the offline mode, or type</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>false</option></userinput>
|
|
</screen>
|
|
<para>to disable offline mode.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>interval</command></term>
|
|
<listitem>
|
|
<para>Returns the currently configured news query interval in
|
|
minutes.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>interval</option></userinput>
|
|
30
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>scrollingSpeed</command></term>
|
|
<listitem>
|
|
<para>Returns the currently configured scrolling speed. The returned
|
|
scrolling speed is specified in pixels per second.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingSpeed</option></userinput>
|
|
20
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>mouseWheelSpeed</command></term>
|
|
<listitem>
|
|
<para>Returns the number of pixels the scrolltext gets shifted
|
|
per mousewheel step.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>mouseWheelSpeed</option></userinput>
|
|
15
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>scrollingDirection</command></term>
|
|
<listitem>
|
|
<para>Returns an integer which corresponds to the direction the
|
|
scrolltext is scrolling in:</para>
|
|
<itemizedlist>
|
|
<listitem><para>1 = To the left</para></listitem>
|
|
<listitem><para>2 = To the right</para></listitem>
|
|
<listitem><para>3 = Upwards</para></listitem>
|
|
<listitem><para>4 = Downwards</para></listitem>
|
|
<listitem><para>5 = Upwards, rotated</para></listitem>
|
|
<listitem><para>6 = Downwards, rotated</para></listitem>
|
|
</itemizedlist>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingDirection</option></userinput>
|
|
1
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>customNames</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
uses custom names for the news sites.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>customNames</option></userinput>
|
|
false
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>endlessScrolling</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
has the endless scrolling option enabled.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>endlessScrolling</option></userinput>
|
|
true
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>scrollMostRecentOnly</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
currently only scrolls the most recent headlines for each news
|
|
site.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollMostRecentOnly</option></userinput>
|
|
false
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>offlineMode</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
is currently in offline mode.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>offlineMode</option></userinput>
|
|
false
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>underlineHighlighted</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
was told to underline the headline which is currently below the mouse
|
|
cursor.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>underlineHighlighted</option></userinput>
|
|
true
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>showIcons</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
currently shows the icon of the news site each particular headline
|
|
was published at in front of the headline.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>showIcons</option></userinput>
|
|
true
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>slowedScrolling</command></term>
|
|
<listitem>
|
|
<para>Returns either 'true' or 'false', depending on whether &knewsticker;
|
|
has the <quote>slowed scrolling</quote> feature activated.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>slowedScrolling</option></userinput>
|
|
false
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>foregroundColor</command></term>
|
|
<listitem>
|
|
<para>Returns the currently configured foreground color as a string
|
|
in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
|
|
<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
|
|
values representing the intensity of the red, green and blue components
|
|
in a scale of 00-ff.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>foregroundColor</option></userinput>
|
|
#804000
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>backgroundColor</command></term>
|
|
<listitem>
|
|
<para>Returns the currently configured background color as a string
|
|
in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
|
|
<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
|
|
values representing the intensity of the red, green and blue components
|
|
in a scale of 00-ff.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>backgroundColor</option></userinput>
|
|
#0030ff
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>highlightedColor</command></term>
|
|
<listitem>
|
|
<para>Returns the currently configured highlight color as a string
|
|
in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
|
|
<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
|
|
values representing the intensity of the red, green and blue components
|
|
in a scale of 00-ff.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>highlightedColor</option></userinput>
|
|
#000080
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>newsSources</command></term>
|
|
<listitem>
|
|
<para>Returns the list of currently registered news sources. Note that
|
|
this returns all news sources, not just the selected ones. In the
|
|
output, each news source name will be printed on a line.</para>
|
|
<para>Example:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>newsSources</option></userinput>
|
|
Freshmeat
|
|
GNOME News
|
|
dot.kde.org
|
|
Slashdot.org
|
|
<prompt>%</prompt>
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
</appendix>
|
|
|
|
&documentation.index;
|
|
|
|
</book>
|