Commit 02f68c4c authored by David Jarvie's avatar David Jarvie
Browse files

Update readme, install notes etc.

parent 057b0a24
KAlarm coding style
===================
KAlarm code should adhere to the following stylistic rules.
SPACING
- No tabs.
- Indent with 4 spaces.
- No spaces inside round or square brackets.
- No space between a function name and the bracket following.
- Place '*' and '&' immediately after the type in declarations, followed by a
space, e.g. "const QString& from", "char* str".
- Normally two spaces on each side of "&&" and "||" in "if"/"while"/"for"
statements.
- Indent "case" within "switch" statements.
BRACES
- Opening brace on a new line.
- No braces are used when only a single statement follows 'if', 'for' etc.
SPLITTING LINES
- There is in general no need to split lines less than 120 characters. Beyond
that length, it's at the coder's discretion.
- Conditional statements occupying line lengths less than 120 characters may be
split for clarity.
- Long "for" statements should be split before each clause at least.
- If a function call or declaration has to be split over more than one line,
indent to after the opening bracket if possible.
- If splitting lines containing expressions, always split BEFORE an operator
("+", "-", "&&" etc.) so that the operator starts the next continuation line.
- In split conditional expressions, position the leading "&&" or "||" before
its enclosing bracket, so that the following expression aligns after the
opening bracket.
NAMING
- Classes, enums, functions and variable names are in camel case (i.e.
separate multiple words by upper-casing each word after the first). Only
use underscores for special purposes.
- Classes and enum names start with an upper case letter.
- Function and variable names start with a lower case letter.
- Enum values are either all upper case with words separated by underscores, or
camel case starting with an upper case letter.
- Constants are all upper case, with words separated by underscores.
- Class member variable names start with "m" followed by a upper case letter.
EXAMPLE
const Animal& ZooCage::releaseAnimal(const QString& name, Species species,
int arrivalNumber) const
{
if (!name.isEmpty()
&& (arrivalNumber > mMinimumSpeciesCount && arrivalNumber < mMaximumSpeciesCount)
|| !arrivalNumber)
{
mLastReleased = Animal(species, name, arrivalNumber);
return mAnimals[name][arrivalNumber];
}
if (name.isEmpty() || mUnclassifiedAnimals.contains(name))
return mUnclassifiedAnimalTypes[species];
}
Requirements
============
The following KDE packages must be installed in order to run KAlarm
successfully:
- kdelibs
- kdepimlibs
- kdebase-runtime (specifically, ktimezoned)
- kdepim-runtime (for the Akonadi based version of KAlarm)
The following optional packages enhance KAlarm if they are installed:
- Jovie (from kdeaccessibility): if installed and configured (together with
compatible speech synthesiser packages), it allows KAlarm to speak
alarm messages when alarms are displayed.
Setting up KAlarm on non-KDE desktops
=====================================
Although KAlarm is a KDE application and requires KDE to be installed on your
system, you can still use it while running other desktops or window managers.
Although KAlarm is a KDE application and requires the above KDE packages to be
installed on your system, you can still use it while running other desktops or
window managers.
In order to have alarms monitored and displayed automatically from one login
session to the next, KAlarm must be run automatically when you graphically log
in or otherwise start X. If you are running the KDE desktop, the KAlarm
installation process sets this up for you.
If you want to use KAlarm with Gnome or another non-KDE window manager, you
have two alternatives:
- GNOME 2
=======
Run Desktop Preferences -> Advanced -> Sessions. In the Sessions dialog,
select the Startup Programs tab and click Add. Enter
'kalarmautostart kalarm --tray' as the Startup Command. This will run KAlarm
in the system tray every time you start up.
- Other Window Managers
=====================
If you want to use KAlarm with a non-KDE window manager:
1) If your desktop environment/window manager performs session restoration,
ensure that the kalarm is included in the session restoration, and that
after login or restarting X kalarm is running with a '-session' command
line option, e.g.
kalarm -session 117f000002000100176495700000008340018
1) If your desktop environment/window manager performs session restoration,
ensure that the kalarm is included in the session restoration, and that
after login or restarting X kalarm is running with a '-session' command
line option, e.g.
You can use the 'ps' command to check this.
kalarm -session 117f000002000100176495700000008340018
Using session restoration will ensure that alarm message windows which
were displayed at the time of logout will be redisplayed when you log in
again.
You can use the 'ps' command to check this.
2) To ensure that KAlarm is always started when you log in, even if it was
not running at logout (so that it wouldn't be included in session
restoration), you should configure one of the following commands to be run
whenever you graphically log in or start X:
2) If you cannot use session restoration to start KAlarm correctly, you
must configure the following command to be run whenever you graphically log
in or start X:
a) If you cannot use session restoration to start KAlarm, run:
kalarm --tray
kalarm --tray
If you have successfully configured session restoration, you should also
configure the following command to be run whenever you graphically log in
or start X:
b) If you use session restoration, you MUST NOT use the above command, but
instead run:
kalarmautostart kalarm --tray
kalarmautostart kalarm --tray
If your desktop environment or window manager has a facility to configure
programs to be run at login, you can use that facility. Otherwise, you need
to add the command to an appropriate script which is run after X is started.
The reason for using this command instead is that if 'kalarm --tray' is
executed while session restoration is already underway, KAlarm will
fail to start. This is an unavoidable consequence of how a KDE
application interacts with session restoration.
If your desktop environment or window manager has a facility to configure
programs to be run at login, you can use that facility. Otherwise, you need
to add the command to an appropriate script which is run after X is started.
If you can send me details on how to set up KAlarm for any particular window
manager, I will include these in the next version of KAlarm.
If you can send me details on how to set up KAlarm for any particular window
manager, I will include these in the next version of KAlarm.
KAlarm
======
KAlarm is a personal alarm message, command and email scheduler. It lets you
set up personal alarm messages which pop up on the screen at the chosen time,
or you can schedule commands to be executed or emails to be sent.
KAlarm is a personal alarm message, audio, command and email scheduler.
When setting up or modifying an alarm, the options available let you:
* choose whether the alarm should display a text message, display a text file,
execute a command, or send an email.
* configure the alarm to recur on an hours/minutes, daily, weekly, monthly or
annual basis, or set it to trigger every time you log in.
* specify that a reminder should be displayed in advance of the main alarm
KAlarm provides a graphical interface to schedule personal timed events -
pop-up alarm messages, playing audio files, command execution and the sending
of emails. It has a wide range of options, including:
* Configuring alarms to recur on an hours/minutes, daily, weekly, monthly or
annual basis, or setting them to trigger every time you log in.
* Choice of whether or not an alarm should be cancelled if it can't be
triggered at its scheduled time. An alarm can only be triggered while you
are logged in and running a graphical environment. If you choose not to
cancel the alarm if it can't be triggered at the correct time, it will be
triggered when you eventually log in.
Options for pop-up alarms include:
* Speaking the message.
* Playing a sound file when the alarm is displayed.
* Setting a reminder to be displayed in advance of, or after, the main alarm
time(s).
* choose a colour and font for displaying the alarm message.
* specify an audible beep or a sound file to play when the message is
displayed.
* choose whether or not the alarm should be cancelled if it can't be triggered
at its scheduled time. An alarm can only be triggered while you are logged
in and running a graphical environment. If you choose not to cancel the
alarm if it can't be triggered at the correct time, it will be triggered
when you eventually log in.
* Selection of the alarm message's colour and font.
In addition to its graphical mode, alarms may also be scheduled from the
command line, or via DCOP calls from other programs.
command line, or via D-Bus calls from other programs.
See the INSTALL file for installation instructions.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment