The LikeBack technology comes from BasKet Note Pads.
This page is the API documentation of LikeBack. Return to the main page of LikeBack.

LikeBack Class Reference

System to Get Quick Feedback from Beta-Testers. More...

#include <likeback.h>

List of all members.

Public Types

enum  Button {
  Like = 0x01, Dislike = 0x02, Bug = 0x04, Feature = 0x10,
  AllButtons = Like | Dislike | Bug | Feature, DefaultButtons = Like | Dislike
}
enum  WindowListing { NoListing = 0, WarnUnnamedWindows = 1, AllWindows = 2 }

Public Slots

void disableBar ()
void enableBar ()
void showInformationMessage ()
void execCommentDialog (Button type=AllButtons, const QString &initialComment="", const QString &windowPath="", const QString &context="")
void askEmailAddress ()

Public Member Functions

 LikeBack (Button buttons=DefaultButtons, bool showBarByDefault=false, KConfig *config=0, KAboutData *aboutData=0)
 ~LikeBack ()
void setWindowNamesListing (WindowListing windowListing)
WindowListing windowNamesListing ()
void setAcceptedLanguages (const QStringList &locales, const QString &message)
QStringList acceptedLocales ()
QString acceptedLanguagesMessage ()
void setServer (const QString &hostName, const QString &remotePath, Q_UINT16 hostPort=80)
QString hostName ()
QString remotePath ()
Q_UINT16 hostPort ()
KAction * sendACommentAction (KActionCollection *parent=0)
Button buttons ()
bool enabledBar ()
bool userWantsToShowBar ()
void setUserWantsToShowBar (bool showBar)
KAboutData * aboutData ()
KConfig * config ()
bool emailAddressAlreadyProvided ()
QString emailAddress ()
void setEmailAddress (const QString &address, bool userProvided=true)

Static Public Member Functions

static QString activeWindowPath ()
static bool isDevelopmentVersion (const QString &version)


Detailed Description

System to Get Quick Feedback from Beta-Testers.

This system allows users to communicate theire liking of the application to its developers. Thus, developers know what theire users prefer of theire applications, what should be enhanced, etc.

Basically, how does it work? Whenever the user notice something good he appreciate or something he do not like, do not understand, do not find polished... he can send a few short words to the developers to tell them what he like or do not like. It is only two or three clicks away. It is fast and efficient.

This greatly lowers the communication barrier between the application developers and the application users. It makes the developers understand and satisfy better the needs of the users.

The LikeBack system has 5 components:

Here is an example of code to call to quickly setup LikeBack on the client:
     // Instanciate the LikeBack system, and show the first-use information dialog if the button-bar is shown:
     LikeBack *likeBack = new LikeBack(LikeBack::AllButtons, LikeBack::isDevelopmentVersion(kapp->aboutData->version())); // Show button-bar only in beta-versions
     likeBack->setServer("myapp.kde.org", "/likeback/send.php");
     likeBack->setAcceptedLanguages(QStringList::split(";", "en;fr"), i18n("Please write in English or French."));

     // Comment the following line once you are sure all your windows have a name:
     likeBack->setWindowNamesListing(LikeBack::WarnUnnamedWindows);

     // This line should be called early in your KMainWindow constructor because it references actionCollection().
     // It should be called before createGUI() for the action to be plugged in the Help menu:
     likeBack->sendACommentAction(actionCollection());

See also:
Visit http://basket.kde.org/likeback.php for more information, screenshots, a tutorial, hints, return of experiences, and to download the server-side developer interface...
Author:
Sebastien Laout <slaout@linux62.org>


Member Enumeration Documentation

enum LikeBack::Button
 

Ids of every LikeBack buttons the button-bar can have. The four first values are each individual buttons you can enable or not. The next ones are combinations: all buttons at once, and the default set of buttons (Like, Dislike). Those values are used in the constructor, to set the allowed type of comments, and when triggering the comment dialog, to set the default checked type.

See also:
The LikeBack constructor and execCommentDialog().
Enumerator:
Dislike  The user select that option to report a positive experience he got with the application.
Bug  The user select that option to report a frustrating experience he got with the application.
Feature  The user select that option to report a bug in the application.
AllButtons  The user select that option to ask for a new feature he desire. If not enabled, the user is explicitely informed she cannot ask for new features.
DefaultButtons  Usable in the constructor to enable every posible buttons.

enum LikeBack::WindowListing
 

Flags letting LikeBack print out name and path of each window you show during execution, for debugging purpose.

See also:
The method setWindowNamesListing() explains how to use those values.
Enumerator:
WarnUnnamedWindows  Do not print out any window name. For release time.
AllWindows  Each time the user option a window, print out a message if the window is unnamed. For development needs, to check windows.


Constructor & Destructor Documentation

LikeBack::LikeBack Button  buttons = DefaultButtons,
bool  showBarByDefault = false,
KConfig *  config = 0,
KAboutData *  aboutData = 0
 

You only need to call the constructor once, typically in main.cpp. Even if you do not show the button-bar by default, you should instanciate LikeBack, to include its action in the Help menu of your application, to let the users send comments or activate the bar.

Parameters:
buttons The types of comments you want to get. Determine which radio-buttons are shown in the comment dialog, and which ones are displayed in the button-bar. Default buttons do not show the Bug and Feature buttons because you are likely to already have a way to get bug and feature reports (most of the time, it is a bugs.kde.org account). If you do not have that, then use the value LikeBack::AllButtons to show every possible buttons.
showBarByDefault Determines if the floating button-bar should also be shown, in addition to the action in the Help menu. Advise: to avoid getting too much noise, enable it only if it is a small application or a development release. Notes: This is only a default value, the user will be able to enable or disabled the bar afterward. The button-bar display is stored by version. On a new version, your default value will take effect again. This allow you to disable the button-bar once the version is stable enought to be released as final.
config Set the configuration file where to store the user email address and if the button-bar should be shown. By default (null), the KApplication configuration object is used.
aboutData Set the KAboutData instance used to get the application name and version. By default (null), the KApplication about data object is used. The application name is only used in the first-use information message. The version is used to store the button-bar visibility per version (can be shown in a development version but not in a final one...) and to send with the comment, so you can filter per version and know if a comment refers the latest version of the application or not.

LikeBack::~LikeBack  ) 
 

Destructor. Also hide the button-bar, if it was shown. Be careful, the KAction is deleted. Do not use it afterward, and take care to unplug it before destroying this LikeBack instance.


Member Function Documentation

KAboutData * LikeBack::aboutData  ) 
 

Returns:
A pointer to the KAboutData used to determin the application name and version.
See also:
The LikeBack constructor for more information.

QString LikeBack::acceptedLanguagesMessage  ) 
 

Returns:
The message displayed to users who are not running the application in an accepted locale.
See also:
setAcceptedLanguages()

QStringList LikeBack::acceptedLocales  ) 
 

Returns:
The list of accepted locales for the user to write comments.
See also:
setAcceptedLanguages()

QString LikeBack::activeWindowPath  )  [static]
 

Returns:
The path of the currently active window. Each windows are separated with "~~". Normally, you should not need to call this method since it is used to send the window path. But if you call execCommentDialog(), you could need to use it.

void LikeBack::askEmailAddress  )  [slot]
 

Popups the dialog for the user to set his email address. The popup will always be shown, even if the user already provided an email address.

LikeBack::Button LikeBack::buttons  ) 
 

Returns:
The combination of buttons that are shown in the comment dialog and the button-bar.

KConfig * LikeBack::config  ) 
 

Returns:
A pointer to the KConfig used to store user configuration (email address, if the button-bar should be shown).
See also:
The LikeBack constructor for more information.

void LikeBack::disableBar  )  [slot]
 

Temporarily disable the button-bar: it is hiden from the screen if it was shown. Does not affect anything if the user has not choosen to show the button-bar.

Note:
Calls to enableBar() and disableBar() are ref-counted. This means that the number of times disableBar() is called is memorized, and enableBar() will only have effect after it has been called as many times as disableBar() was called before. So, make sure to always call enableBar() the same number of times ou called disableBar(). And please make sure to ALWAYS call disableBar() BEFORE enableBar(). In the counter-case, another code could call disableBar() and EXCPECT the bar to be disabled. But it will not, because its call only canceled yours.

Sometimes, you will absolutely need to call enableBar() before disableBar(). For instance, MyWindow::show() calls enableBar() and MyWindow::hide() calls disableBar(). This is the trick used to show the LikeBack button-bar of a Kontact plugin only when the main widget of that plugin is active. In this case, call disableBar() at the begin of your program, so the disable count will never be negative.

If the bar is enabled, it does not mean the bar is shown. For that, the developer (using showBarByDefault in the construcor) or the user (by checking the checkbox in the comment dialog) have to explicitely show the bar.

QString LikeBack::emailAddress  ) 
 

Returns:
The email user address, or ask it to the user if he have not provided or ignored it.

An empty string if the user cancelled the request dialog.

bool LikeBack::emailAddressAlreadyProvided  ) 
 

During the first comment sending, the user is invited to enter his email address for the developers to be able to contact him back. He is only asked once, or he can set or change it by using the bottom-left button in the comment dialog.

Returns:
true if the user has already configured his email address.

void LikeBack::enableBar  )  [slot]
 

Re-enable the button-bar one time.

See also:
The method disableBar() for more information on how enabling/disabling works.

bool LikeBack::enabledBar  ) 
 

Returns:
true if the button-bar is currently enabled. Ie, if it has been re-enabled as many times as it has been disabled.
See also:
The method disableBar() for more information on how enabling/disabling works.

void LikeBack::execCommentDialog Button  type = AllButtons,
const QString &  initialComment = "",
const QString &  windowPath = "",
const QString &  context = ""
[slot]
 

Popup the comment dialog. With no parameter, it popups in the default configuration: the first type is checked, empty message, current window path, and empty context. You can use the following parameters to customize how it should appears:

Parameters:
type Which radiobutton should be checked when poping up. AllButton, the default value, means the first available type will be checked.
initialComment The text to put in the comment text area. Allows you to popup the dialog in some special circumstances, like to let the user report an internal error by populating the comment area with technical details useful for you to debug.
windowPath The window path to send with the comment. If empty (the default), the current window path is took. Separate window names with "~~". For instance "MainWindow~~NewFile~~FileOpen". If you popup the dialog after an error occurred, you can put the error name in that field (if the window path has no sense in that context). When the dialog is popuped up from the sendACommentAction() KAction, this value is "HelpMenu", because there is no way to know if the user is commenting a thing he found/thinked about in a sub-dialog.
context Not used for the moment. Will allow more fine-grained application status report.

QString LikeBack::hostName  ) 
 

Returns:
The server host name to contact when sending comments.
See also:
setServer()

Q_UINT16 LikeBack::hostPort  ) 
 

Returns:
The port used to contact the server using the HTTP protocol.
See also:
setServer()

bool LikeBack::isDevelopmentVersion const QString &  version  )  [static]
 

Returns:
true if version is an Alpha, Beta, RC, SVN or CVS version. You can use this static method in the constructor to enable the button-bar by default only during beta-releases.

QString LikeBack::remotePath  ) 
 

Returns:
The path to the send script on the server.
See also:
setServer()

KAction * LikeBack::sendACommentAction KActionCollection *  parent = 0  ) 
 

Get the KAction letting user to show the comment dialog. You should plug it in your Help menu, just bellow the "Report a Bug" action, or replace it. Adding the action below "Report a Bug" or replacing "Report a Bug" depends on your application and if you have a Bugzilla account. If you do not have a Bugzilla account, LikeBack is a good way for your small application to get bug reports: remove "Report a Bug". For more information about how to configure LikeBack depending on your application size and settings, see the constructor documentation.

Note:
The action is named "likeback_send_a_comment". So you should add the following XML in the *ui.rc file of your application:
       <Action name="likeback_send_a_comment" />

void LikeBack::setAcceptedLanguages const QStringList &  locales,
const QString &  message
 

By default, only English comments are accepted. The user is informed she must write in this language by a sentence placed in the comment dialog. If you have people talking other languages in your development team, it can be interesting to call this method to define the accepted locales (languages), and provide a message to inform users. The developer interface on the server let developers view comments in theire locale. Note that no verification is done to check if the user used the right language, it would be impossible. The list of locales is there to make it possible to NOT show the message for users of the accepted languages. For instance, if you accept only English and French, and that the application run in a French environment, it is likely the user is French and will write comments using French. Telling him he should write in French is unnecessary and redundant. Passing an empty list and an empty string to the method will make LikeBack display the default message telling the user only English is accepted. Example of call you can quickly copy, paste and adapt:

     likeBack->setAcceptedLanguages(QStringList::split(";", "en;fr"), i18n("Please write in English or French."));
Note:
During tests, if you do not see the sentence, it is because you are running the application with an "accepted language": do not be surprised ;-)
Parameters:
locales The list of locales where the message does not need to be shown. See TODO TODO for a list of available locales for you to choose.
message The message to displays to the user to tell him what languages are accepted to write his comments.

void LikeBack::setEmailAddress const QString &  address,
bool  userProvided = true
 

Define or re-define the user email address. LikeBack will not ask it again to the user, unless you set userProvided to false. Then, this call can be considered as setting the default email address, that the user should confirm later.

void LikeBack::setServer const QString &  hostName,
const QString &  remotePath,
Q_UINT16  hostPort = 80
 

Set the path where LikeBack should send every comments. It is composed of the server host name, the path to the PHP script used to send comments, and optionnaly a port number if it is not 80. This call is mandatory for LikeBack to work.

Parameters:
hostName The server host name to contact when sending comments. For instance "myapp.kde.org".
remotePath The path to the send script on the server. For instance, "/likeback/send.php".
hostPort Optionnal port used to contact the server using the HTTP protocol. By default, it is port 80.

void LikeBack::setUserWantsToShowBar bool  showBar  ) 
 

Explicitely set if the floating button-bar should be shown or not. Tehorically, this choice should only be left to the user, and to the developers for the default value, already provided in the constructor.

void LikeBack::setWindowNamesListing WindowListing  windowListing  ) 
 

This method is interesting while setting up the system for the first time. LikeBack send the current window name (and hierarchy) with the comment. This allows you to put the comments in theire context. So, of course, you are encouraged to give a name to your windows. It is done in the constructor of the widgets. This method allows to output the name of the current window to the standard output. So you can use the application, open all the windows, and when you see a warning, you know which window you should assign a name.

See also:
The WindowListing flags for an enumeration and explaining of every possibilities.
Note:
If you do not name your windows, the name of the classes will be sent. So it is not that grave.

void LikeBack::showInformationMessage  )  [slot]
 

Show the first-use information dialog telling the user the meaning of the LikeBack system and giving examples of every comment types.

bool LikeBack::userWantsToShowBar  ) 
 

Returns:
true if the user has enabled the LikeBack bar for this version.

LikeBack::WindowListing LikeBack::windowNamesListing  ) 
 

Returns:
The window listing flag.
See also:
setWindowNamesListing()


The documentation for this class was generated from the following files:
Generated on Tue Aug 29 20:13:36 2006 for basket.kdevelop by  doxygen 1.4.6