polkit-tqt/Mainpage.dox

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

\section polkit-tqt_overview Overview

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

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

\b polkit-tqt-core 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 lets you easily associate GUI items with polkit actions. Through some simple
wrapper classes you are able to associate TQAction and TQButton 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 lets you write your own polkit authentication agents in a very simple way.

\b A sample usage of polkit-tqt can be found in \ref polkit-tqt_example


\page polkit-tqt-example Polkit-tqt usage example

You can find an example usage of Polkit-tqt in the examples/ dir. You can
build it by passing \c -DBUILD_EXAMPLES=TRUE to your cmake line. It demonstrates
how easy it is to integrate polkit support in an existing application.
Let's see some details about it:

\code
// Previously defined TQPushButton
kickPB = new TQPushButton(privateLayoutWidget, "kickPB");
...
// Setup polkit tqt action
ActionButton *bt;
bt = new ActionButton(kickPB, "org.tqt.policykit.examples.kick", this);
bt->setText("Kick!");
// here we set the behavior of PolKitResult = No
bt->setText("Can't kick", Action::No);
bt->setVisible(true, Action::No);
bt->setEnabled(true, Action::No);
bt->setIconSet(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 PolKitResult = Auth
bt->setVisible(true, Action::Auth);
bt->setEnabled(true, Action::Auth);
bt->setText("Kick?", 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 PolKitResult = Yes
bt->setVisible(true, Action::Yes);
bt->setEnabled(true, Action::Yes);
bt->setText("Kick!", 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 already
defined, \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(TQValueList<TQButton*>() << 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 are kept in sync with the action.

\code
connect(bt, SIGNAL(activated()), this, SLOT(activateAction()));
connect(bt, SIGNAL(clicked(TQButton*, 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::activated()
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(), and
Action::authorized() signal notifies you when polkit has authorized you to perform the action.

As you can see, usage of polkit-tqt 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
// DOXYGEN_ENABLE=YES