polkit-tqt/Mainpage.dox

/**
\mainpage Polkit-tqt-1 - TQt wrapper around polkit-1

\section polkittqt1_overview Overview

polkit-tqt-1 aims to make it easy for TQt developers to take advantage of
polkit API. It is a convenience wrapper around QAction and QAbstractButton
that lets you integrate those two components easily with polkit.

polkit-tqt-1 is split in three libraries: polkit-tqt-core-1, polkit-tqt-gui-1 and polkit-tqt-agent-1

\b polkit-tqt-core-1 lets you control actions and authentication without a GUI, with some very
simple functions. It also lets you retrieve and control useful informations on the polkit
authority. You will be mostly interested in the \c Authority class.

\b polkit-tqt-gui-1 lets you easily associate GUI items with polkit actions. Through some simple
wrapper classes you are able to associate QAction and QAbstractButton to a polkit action,
and get their properties changed accordingly to polkit's result. It includes the classes
Action, ActionButton and ActionButtons

\b polkit-tqt-agent-1 lets you write your own polkit authentication agents in a very simple way.

\li A sample usage of polkit-tqt-1 can be found in \ref polkittqt1_example
\li <a href="classes.html">Alphabetical Class List</a>
\li <a href="hierarchy.html">Class Hierarchy</a>




\page polkittqt1_example Polkit-tqt-1 usage example

You can find an example usage of Polkit-tqt-1 in the examples/ dir. You can
build it by passing \c -DBUILD_EXAMPLES=TRUE to your cmake line. The structure
consists of a .ui file and a main class, to demonstrate how easy it is to integrate
polkit support in an existing application. Let's see some details about it:

\code
bt = new ActionButton(kickPB, "org.tqt.policykit.examples.kick", this);
bt->setText("Kick... (long)");
// here we set the behavior of PolKitResul = No
bt->setVisible(true, Action::No);
bt->setEnabled(true, Action::No);
bt->setText("Kick (long)", Action::No);
bt->setIcon(TQPixmap(":/Icons/custom-no.png"), Action::No);
bt->setToolTip("If your admin wasn't annoying, you could do this", Action::No);
// here we set the behavior of PolKitResul = Auth
bt->setVisible(true, Action::Auth);
bt->setEnabled(true, Action::Auth);
bt->setText("Kick... (long)", Action::Auth);
bt->setIcon(TQPixmap(":/Icons/action-locked-default.png"), Action::Auth);
bt->setToolTip("Only card carrying tweakers can do this!", Action::Auth);
// here we set the behavior of PolKitResul = Yes
bt->setVisible(true, Action::Yes);
bt->setEnabled(true, Action::Yes);
bt->setText("Kick! (long)", Action::Yes);
bt->setIcon(TQPixmap(":/Icons/custom-yes.png"), Action::Yes);
bt->setToolTip("Go ahead, kick kick kick!", Action::Yes);
\endcode

This small paragraph sets up an action button using an existing button defined in the
UI file, \c kickPB . As you can see, you can set custom properties on your button depending
on the action status/result. The code is mostly self-explainatory

\code
bt = new ActionButtons(TQList<TQAbstractButton*>() << listenPB << listenCB,
                           "org.tqt.policykit.examples.listen", this);
bt->setIcon(TQPixmap(":/Icons/action-locked.png"));
bt->setIcon(TQPixmap(":/Icons/action-unlocked.png"), Action::Yes);
bt->setText("Click to make changes...");
\endcode

This demonstrates the use of ActionButtons, that lets you associate multiple buttons with a
single action with extreme ease. \c listenPB and \c listenCB, both defined in the ui file,
are kept in sync with the action.

\code
connect(bt, SIGNAL(triggered(bool)), this, SLOT(activateAction()));
connect(bt, SIGNAL(clicked(TQAbstractButton*,bool)), bt, SLOT(activate()));
connect(bt, SIGNAL(authorized()), this, SLOT(actionActivated()));
\endcode

Those three signals are all you need to control the action and the activation. Action::triggered()
lets you start the activation/revoke when needed, ActionButton::clicked() lets you do the same thing
with even more ease, just by manually connecting the signal to ActionButton::activate() (see the docs
to understand why this connection doesn't happen automatically), and Action::authorized() signal notifies
you when polkit has authorized you to perform the action.

As you can see, usage of polkit-tqt-1 is extremely simple. Have a look at the complete example
and to the API Docs for more details.


*/

// DOXYGEN_PROJECTVERSION=0.96.1
// DOXYGEN_PROJECTNAME=polkittqt-1
// DOXYGEN_ENABLE=YES