NfcSettingsApplication/widget.h

/*
* Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Part of Qt NFC Setting sample application.
*/

/*!
 * \file
 * \brief Declaration of the Widget class.
 *
 * This file contains the declaration of the Widget class that acts as the
 * central widget of the main window of the application.
 *
 * \note The MainWindow class declared in mainwindow.h is not documented here,
 * as it is a class generated by the Qt Creator project wizard.
 */

#ifndef WIDGET_H
#define WIDGET_H

#include <QtGui/QWidget>

#include "nfcsettings.h"

namespace Ui {
    class Widget;
}

/*!
 * \brief The central widget of the Qt NFC Settings application main window.
 *
 * This class represents the user interface of the application. The user
 * interface contains a label for showing the current NFC mode setting value,
 * a secondary label for showing any error messages and a push button used to
 * exit the application.
 *
 * The Widget class corresponds to the Qt Designer UI file widget.ui. A Widget
 * is shown as the central widget in the <code>QMainWindow</code> derived
 * MainWindow that is the top-level widget of this application.
 *
 * An instance of the class NfcSettings is constructed when the widget is
 * constructed to obtain information on whether device supports NFC and if so,
 * what the current NFC mode is. This information is displayed on the label
 * that is a child of this central widget.
 *
 * \note The MainWindow class is not documented here, as it is a class generated
 * by the Qt Creator project wizard.
 *
 * \see MainWindow, NfcSettings
 */
class Widget : public QWidget
{
    Q_OBJECT

public:

   /*!
    * \brief C++ constructor.
    *
    * Initializes a new Widget instance. Sets up the user interface, fetches
    * the initial value of the NFC mode setting and connects the mode change
    * and error signals to the handleNfcModeChange() and handleNfcError() slots
    * implemented in this class for handling them.
    *
    * \param parent The widget that is to be the parent of this widget, always
    * an instance of MainWindow.
    * \see MainWindow, NfcSettings
    */
    explicit Widget(QWidget *parent = 0);

    /*!
     * \brief C++ destructor.
     *
     * Releases any resources allocated by this Widget instance.
     */
    ~Widget();

protected slots:

    /*!
     * \brief Displays the NFC feature support level on a label in the user
     * interface.
     *
     * This function maps the NFC feature enumeration value to a human readable
     * message and displays on the user interface.
     *
     * \note Even though this function is declared as a slot, there is not
     * corresponding signal in the NfcSettings class as the NFC feature
     * support cannot change at runtime.
     *
     * \param nfcFeature The level of NFC support provided by the device and
     * current software version, i.e. whether NFC hardware is present and
     * supported by the software.
     * \see NfcSettings::NfcFeature, NfcSettings::nfcFeature()
     */
    void displayNfcFeature(NfcSettings::NfcFeature nfcFeature);

    /*!
     * \brief Displays the current NFC mode on a label in the user interface.
     *
     * This function maps the NFC mode enumeration value to a human readable
     * message and displays on the user interface.
     *
     * \param nfcMode The current value of the NFC mode setting.
     * \see NfcSettings::NfcMode, NfcSettings::nfcModeChanged()
     */
    void displayNfcMode(NfcSettings::NfcMode nfcMode);

    /*!
     * \brief Displays the latest NFC error message on a label in the user
     * interface.
     *
     * This function maps the NFC error enumeration value to a human readable
     * status message and displays it along with the associated error code on
     * the user interface.
     *
     * \param nfcError The general reason for the error.
     * \param error A platform specific error code giving a more detailed
     * description of the error that took place.
     * \see NfcSettings::NfcError, NfcSettings::nfcErrorOccurred()
     */
    void displayNfcError(NfcSettings::NfcError nfcError, int error);

private:

    /*! \brief An instance of the UI class generated from Qt Designer file widget.ui, owned. */
    Ui::Widget *ui;

    /*! \brief The NFC settings object used to query and monitor the NFC mode setting, owned. */
    NfcSettings *m_nfcSettings;
};

#endif // WIDGET_H