Warning, /libraries/polkit-qt-1/Mainpage.dox is written in an unsupported language. File is not indexed.

0001 /**
0002 \mainpage Polkit-qt-1 - Qt wrapper around polkit-1
0003 
0004 \section polkitqt1_overview Overview
0005 
0006 \note Please note that if you're developing an application which can rely not just on Qt modules,
0007       but also Qt extensions like from the KDE Frameworks, you might want to use instead
0008       KAuth from KDE Frameworks.
0009 
0010 polkit-qt-1 aims to make it easy for Qt developers to take advantage of
0011 polkit API. It is a convenience wrapper around QAction and QAbstractButton
0012 that lets you integrate those two components easily with polkit.
0013 
0014 polkit-qt-1 is not a direct replacement of polkit-qt: it is based on polkit-1, which is not
0015 backwards compatible in any way with Policykit <= 0.9, which was the backend of polkit-qt.
0016 You are encouraged to port polkit-qt applications to polkit-qt or KAuth (from KDE Frameworks),
0017 since PolicyKit <= 0.9 is no longer maintained.
0018 
0019 polkit-qt-1 is split in three libraries: polkit-qt-core-1, polkit-qt-gui-1 and polkit-qt-agent-1
0020 
0021 \b polkit-qt-core-1 lets you control actions and authentication without a GUI, with some very
0022 simple functions. It also lets you retrieve and control useful information on the polkit
0023 authority. You will be mostly interested in the \c Authority class.
0024 
0025 \b polkit-qt-gui-1 lets you easily associate GUI items with polkit actions. Through some simple
0026 wrapper classes you are able to associate QAction and QAbstractButton to a polkit action,
0027 and get their properties changed accordingly to polkit's result. It includes the classes
0028 Action, ActionButton and ActionButtons
0029 
0030 \b polkit-qt-agent-1 lets you write your own polkit authentication agents in a very simple way.
0031 
0032 \li A sample usage of polkit-qt-1 can be found in \ref polkitqt1_example
0033 \li <a href="classes.html">Alphabetical Class List</a>
0034 \li <a href="hierarchy.html">Class Hierarchy</a>
0035 
0036 
0037 
0038 
0039 \page polkitqt1_example Polkit-qt-1 usage example
0040 
0041 You can find an example usage of Polkit-qt-1 in the examples/ dir. You can
0042 build it by passing \c -DBUILD_EXAMPLES=TRUE to your cmake line. The structure
0043 consists of a .ui file and a main class, to demonstrate how easy it is to integrate
0044 polkit support in an existing application. Let's see some details about it:
0045 
0046 \code
0047 bt = new ActionButton(kickPB, "org.qt.policykit.examples.kick", this);
0048 bt->setText("Kick... (long)");
0049 // here we set the behavior of PolKitResul = No
0050 bt->setVisible(true, Action::No);
0051 bt->setEnabled(true, Action::No);
0052 bt->setText("Kick (long)", Action::No);
0053 bt->setIcon(QPixmap(":/Icons/custom-no.png"), Action::No);
0054 bt->setToolTip("If your admin wasn't annoying, you could do this", Action::No);
0055 // here we set the behavior of PolKitResul = Auth
0056 bt->setVisible(true, Action::Auth);
0057 bt->setEnabled(true, Action::Auth);
0058 bt->setText("Kick... (long)", Action::Auth);
0059 bt->setIcon(QPixmap(":/Icons/action-locked-default.png"), Action::Auth);
0060 bt->setToolTip("Only card carrying tweakers can do this!", Action::Auth);
0061 // here we set the behavior of PolKitResul = Yes
0062 bt->setVisible(true, Action::Yes);
0063 bt->setEnabled(true, Action::Yes);
0064 bt->setText("Kick! (long)", Action::Yes);
0065 bt->setIcon(QPixmap(":/Icons/custom-yes.png"), Action::Yes);
0066 bt->setToolTip("Go ahead, kick kick kick!", Action::Yes);
0067 \endcode
0068 
0069 This small paragraph sets up an action button using an existing button defined in the
0070 UI file, \c kickPB . As you can see, you can set custom properties on your button depending
0071 on the action status/result. The code is mostly self-explainatory
0072 
0073 \code
0074 bt = new ActionButtons(QList<QAbstractButton*>() << listenPB << listenCB,
0075                            "org.qt.policykit.examples.listen", this);
0076 bt->setIcon(QPixmap(":/Icons/action-locked.png"));
0077 bt->setIcon(QPixmap(":/Icons/action-unlocked.png"), Action::Yes);
0078 bt->setText("Click to make changes...");
0079 \endcode
0080 
0081 This demonstrates the use of ActionButtons, that lets you associate multiple buttons with a
0082 single action with extreme ease. \c listenPB and \c listenCB, both defined in the ui file,
0083 are kept in sync with the action.
0084 
0085 \code
0086 connect(bt, SIGNAL(triggered(bool)), this, SLOT(activateAction()));
0087 connect(bt, SIGNAL(clicked(QAbstractButton*,bool)), bt, SLOT(activate()));
0088 connect(bt, SIGNAL(authorized()), this, SLOT(actionActivated()));
0089 \endcode
0090 
0091 Those three signals are all you need to control the action and the activation. Action::triggered()
0092 lets you start the activation/revoke when needed, ActionButton::clicked() lets you do the same thing
0093 with even more ease, just by manually connecting the signal to ActionButton::activate() (see the docs
0094 to understand why this connection doesn't happen automatically), and Action::authorized() signal notifies
0095 you when polkit has authorized you to perform the action.
0096 
0097 As you can see, usage of polkit-qt-1 is extremely simple. Have a look at the complete example
0098 and to the API Docs for more details.
0099 
0100 
0101 */
0102 
0103 // DOXYGEN_PROJECTVERSION=0.96.1
0104 // DOXYGEN_PROJECTNAME=PolkitQt-1
0105 // DOXYGEN_ENABLE=YES
0106 
0107 // vim:ts=4:sw=4:expandtab:filetype=doxygen