Improve documentation for UI classes

This commit is contained in:
Wladimir J. van der Laan 2011-11-13 13:19:52 +01:00
parent 66112ed6e6
commit af836ad588
28 changed files with 188 additions and 131 deletions

View file

@ -8,6 +8,7 @@ namespace Ui {
}
class ClientModel;
/** "About" dialog box */
class AboutDialog : public QDialog
{
Q_OBJECT

View file

@ -14,6 +14,8 @@ class QItemSelection;
class QSortFilterProxyModel;
QT_END_NAMESPACE
/** Widget that shows a list of sending or receiving addresses.
*/
class AddressBookPage : public QDialog
{
Q_OBJECT
@ -25,8 +27,8 @@ public:
};
enum Mode {
ForSending, // Pick address for sending
ForEditing // Open address book for editing
ForSending, /**< Open address book to pick address for sending */
ForEditing /**< Open address book for editing */
};
explicit AddressBookPage(Mode mode, Tabs tab, QWidget *parent = 0);

View file

@ -8,6 +8,9 @@ class AddressTablePriv;
class CWallet;
class WalletModel;
/**
Qt model of the address book in the core. This allows views to access and modify the address book.
*/
class AddressTableModel : public QAbstractTableModel
{
Q_OBJECT
@ -16,27 +19,28 @@ public:
~AddressTableModel();
enum ColumnIndex {
Label = 0, /* User specified label */
Address = 1 /* Bitcoin address */
Label = 0, /**< User specified label */
Address = 1 /**< Bitcoin address */
};
enum RoleIndex {
TypeRole = Qt::UserRole
TypeRole = Qt::UserRole /**< Type of address (#Send or #Receive) */
};
// Return status of last edit/insert operation
/** Return status of edit/insert operation */
enum EditStatus {
OK,
INVALID_ADDRESS,
DUPLICATE_ADDRESS,
WALLET_UNLOCK_FAILURE,
KEY_GENERATION_FAILURE
INVALID_ADDRESS, /**< Unparseable address */
DUPLICATE_ADDRESS, /**< Address already in address book */
WALLET_UNLOCK_FAILURE, /**< Wallet could not be unlocked to create new receiving address */
KEY_GENERATION_FAILURE /**< Generating a new public key for a receiving address failed */
};
static const QString Send; /* Send addres */
static const QString Receive; /* Receive address */
static const QString Send; /**< Specifies send address */
static const QString Receive; /**< Specifies receive address */
/* Overridden methods from QAbstractTableModel */
/** @name Methods overridden from QAbstractTableModel
@{*/
int rowCount(const QModelIndex &parent) const;
int columnCount(const QModelIndex &parent) const;
QVariant data(const QModelIndex &index, int role) const;
@ -45,6 +49,7 @@ public:
QModelIndex index(int row, int column, const QModelIndex & parent) const;
bool removeRows(int row, int count, const QModelIndex & parent = QModelIndex());
Qt::ItemFlags flags(const QModelIndex & index) const;
/*@}*/
/* Add an address to the model.
Returns the added address on success, and an empty string otherwise.

View file

@ -9,16 +9,18 @@ namespace Ui {
class WalletModel;
/** Multifunctional dialog to ask for passphrases. Used for encryption, unlocking, and changing the passphrase.
*/
class AskPassphraseDialog : public QDialog
{
Q_OBJECT
public:
enum Mode {
Encrypt, // Ask passphrase x2
Unlock, // Ask passphrase
ChangePass, // Ask old passphrase + new passphrase x2
Decrypt // Ask passphrase
Encrypt, /**< Ask passphrase twice and encrypt */
Unlock, /**< Ask passphrase and unlock */
ChangePass, /**< Ask old passphrase + new passphrase twice */
Decrypt /**< Ask passphrase and decrypt wallet */
};
explicit AskPassphraseDialog(Mode mode, QWidget *parent = 0);

View file

@ -3,7 +3,7 @@
#include <QRegExpValidator>
/* Base48 entry widget validator.
/** Base48 entry widget validator.
Corrects near-miss characters and refuses characters that are no part of base48.
*/
class BitcoinAddressValidator : public QValidator

View file

@ -8,8 +8,8 @@ class QDoubleSpinBox;
class QValueComboBox;
QT_END_NAMESPACE
// Coin amount entry widget with separate parts for whole
// coins and decimals.
/** Widget for entering bitcoin amounts.
*/
class BitcoinAmountField: public QWidget
{
Q_OBJECT
@ -20,25 +20,27 @@ public:
qint64 value(bool *valid=0) const;
void setValue(qint64 value);
// Mark current valid as invalid in UI
/** Mark current value as invalid in UI. */
void setValid(bool valid);
/** Perform input validation, mark field as invalid if entered value is not valid. */
bool validate();
// Change current unit
/** Change unit used to display amount. */
void setDisplayUnit(int unit);
// Make field empty and ready for new input
/** Make field empty and ready for new input. */
void clear();
// Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907)
// Hence we have to set it up manually
/** Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907),
in these cases we have to set it up manually.
*/
QWidget *setupTabChain(QWidget *prev);
signals:
void textChanged();
protected:
// Intercept focus-in event and ',' keypresses
/** Intercept focus-in event and ',' keypresses */
bool eventFilter(QObject *object, QEvent *event);
private:

View file

@ -4,51 +4,60 @@
#include <QString>
#include <QAbstractListModel>
// Bitcoin unit definitions, encapsulates parsing and formatting
// and serves as list model for dropdown selection boxes.
/** Bitcoin unit definitions. Encapsulates parsing and formatting
and serves as list model for dropdown selection boxes.
*/
class BitcoinUnits: public QAbstractListModel
{
public:
explicit BitcoinUnits(QObject *parent);
/** Bitcoin units.
@note Source: https://en.bitcoin.it/wiki/Units . Please add only sensible ones
*/
enum Unit
{
// Source: https://en.bitcoin.it/wiki/Units
// Please add only sensible ones
BTC,
mBTC,
uBTC
};
/// Static API
// Get list of units, for dropdown box
static QList<Unit> availableUnits();
// Is unit ID valid?
static bool valid(int unit);
// Short name
static QString name(int unit);
// Longer description
static QString description(int unit);
// Number of satoshis / unit
static qint64 factor(int unit);
// Number of amount digits (to represent max number of coins)
static int amountDigits(int unit);
// Number of decimals left
static int decimals(int unit);
// Format as string
static QString format(int unit, qint64 amount, bool plussign=false);
// Format as string (with unit)
static QString formatWithUnit(int unit, qint64 amount, bool plussign=false);
// Parse string to coin amount
static bool parse(int unit, const QString &value, qint64 *val_out);
//! @name Static API
//! Unit conversion and formatting
///@{
/// AbstractListModel implementation
enum {
// Unit identifier
//! Get list of units, for dropdown box
static QList<Unit> availableUnits();
//! Is unit ID valid?
static bool valid(int unit);
//! Short name
static QString name(int unit);
//! Longer description
static QString description(int unit);
//! Number of Satoshis (1e-8) per unit
static qint64 factor(int unit);
//! Number of amount digits (to represent max number of coins)
static int amountDigits(int unit);
//! Number of decimals left
static int decimals(int unit);
//! Format as string
static QString format(int unit, qint64 amount, bool plussign=false);
//! Format as string (with unit)
static QString formatWithUnit(int unit, qint64 amount, bool plussign=false);
//! Parse string to coin amount
static bool parse(int unit, const QString &value, qint64 *val_out);
///@}
//! @name AbstractListModel implementation
//! List model for unit dropdown selection box.
///@{
enum RoleIndex {
/** Unit identifier */
UnitRole = Qt::UserRole
} RoleIndex;
};
int rowCount(const QModelIndex &parent) const;
QVariant data(const QModelIndex &index, int role) const;
///@}
private:
QList<BitcoinUnits::Unit> unitlist;
};

View file

@ -12,7 +12,7 @@ QT_BEGIN_NAMESPACE
class QDateTime;
QT_END_NAMESPACE
// Model for Bitcoin network client
/** Model for Bitcoin network client. */
class ClientModel : public QObject
{
Q_OBJECT
@ -27,11 +27,11 @@ public:
QDateTime getLastBlockDate() const;
// Return true if client connected to testnet
//! Return true if client connected to testnet
bool isTestNet() const;
// Return true if core is doing initial block download
//! Return true if core is doing initial block download
bool inInitialBlockDownload() const;
// Return conservative estimate of total number of blocks, or 0 if unknown
//! Return conservative estimate of total number of blocks, or 0 if unknown
int getNumBlocksOfPeers() const;
QString formatFullVersion() const;
@ -48,7 +48,7 @@ signals:
void numConnectionsChanged(int count);
void numBlocksChanged(int count);
// Asynchronous error notification
//! Asynchronous error notification
void error(const QString &title, const QString &message);
public slots:

View file

@ -8,7 +8,9 @@ QT_BEGIN_NAMESPACE
class QAbstractItemModel;
QT_END_NAMESPACE
// Export TableModel to CSV file
/** Export a Qt table model to a CSV file. This is useful for analyzing or post-processing the data in
a spreadsheet.
*/
class CSVModelWriter : public QObject
{
Q_OBJECT
@ -18,8 +20,9 @@ public:
void setModel(const QAbstractItemModel *model);
void addColumn(const QString &title, int column, int role=Qt::EditRole);
// Perform write operation
// Returns true on success, false otherwise
/** Perform export of the model to CSV.
@returns true on success, false otherwise
*/
bool write();
private:

View file

@ -12,6 +12,8 @@ namespace Ui {
}
class AddressTableModel;
/** Dialog for editing an address and associated information.
*/
class EditAddressDialog : public QDialog
{
Q_OBJECT

View file

@ -12,6 +12,8 @@ class QUrl;
QT_END_NAMESPACE
class SendCoinsRecipient;
/** Static utility functions used by the Bitcoin Qt UI.
*/
class GUIUtil
{
public:

View file

@ -8,6 +8,8 @@ class QIcon;
class QWidget;
class objc_object;
/** Macintosh-specific dock icon handler.
*/
class MacDockIconHandler : public QObject
{
Q_OBJECT

View file

@ -7,9 +7,8 @@ QT_BEGIN_NAMESPACE
class QWidget;
QT_END_NAMESPACE
/* Data <-> Widget mapper that watches for changes,
to be able to notify when 'dirty' (for example, to
enable a commit/apply button).
/** Data to Widget mapper that watches for edits and notifies listeners when a field is edited.
This can be used, for example, to enable a commit/apply button in a configuration dialog.
*/
class MonitoredDataMapper : public QDataWidgetMapper
{

View file

@ -11,33 +11,34 @@ class QDBusInterface;
#endif
QT_END_NAMESPACE
// Cross-platform desktop notification client
/** Cross-platform desktop notification client. */
class Notificator: public QObject
{
Q_OBJECT
public:
// Create a new notificator
// Ownership of trayIcon is not transferred to this object
/** Create a new notificator.
@note Ownership of trayIcon is not transferred to this object.
*/
Notificator(const QString &programName=QString(), QSystemTrayIcon *trayIcon=0, QWidget *parent=0);
~Notificator();
// Message class
enum Class
{
Information,
Warning,
Critical,
Information, /**< Informational message */
Warning, /**< Notify user of potential problem */
Critical /**< An error occured */
};
public slots:
/* Show notification message.
*
* cls: general message class
* title: title shown with message
* text: message content
* icon: optional icon to show with message
* millisTimeout: notification timeout in milliseconds (default 10 seconds)
/** Show notification message.
@param[in] cls general message class
@param[in] title title shown with message
@param[in] text message content
@param[in] icon optional icon to show with message
@param[in] millisTimeout notification timeout in milliseconds (defaults to 10 seconds)
@note Platform implementations are free to ignore any of the provided fields except for \a text.
*/
void notify(Class cls, const QString &title, const QString &text,
const QIcon &icon = QIcon(), int millisTimeout = 10000);
@ -45,10 +46,10 @@ public slots:
private:
QWidget *parent;
enum Mode {
None,
Freedesktop, // Use DBus org.freedesktop.Notifications
QSystemTray, // Use QSystemTray::showMessage
Growl // Use the Growl notification system (Mac only)
None, /**< Ignore informational notifications, and show a modal pop-up dialog for Critical notifications. */
Freedesktop, /**< Use DBus org.freedesktop.Notifications */
QSystemTray, /**< Use QSystemTray::showMessage */
Growl /**< Use the Growl notification system (Mac only) */
};
QString programName;
Mode mode;

View file

@ -14,6 +14,7 @@ class MainOptionsPage;
class DisplayOptionsPage;
class MonitoredDataMapper;
/** Preferences dialog. */
class OptionsDialog : public QDialog
{
Q_OBJECT
@ -25,6 +26,7 @@ public:
signals:
public slots:
/** Change the current page to \a index. */
void changePage(int index);
private slots:
@ -33,6 +35,7 @@ private slots:
void applyClicked();
void enableApply();
void disableApply();
private:
QListWidget *contents_widget;
QStackedWidget *pages_widget;

View file

@ -5,7 +5,7 @@
class CWallet;
/* Interface from QT to configuration data structure for bitcoin client.
/** Interface from QT to configuration data structure for bitcoin client.
To QT, the options are presented as a list with the different options
laid out vertically.
This can be changed to a tree once the settings become sufficiently

View file

@ -13,6 +13,7 @@ namespace Ui {
class WalletModel;
class TxViewDelegate;
/** Overview ("home") page widget */
class OverviewPage : public QWidget
{
Q_OBJECT

View file

@ -3,8 +3,9 @@
#include <QLineEdit>
// Line edit that can be marked as "invalid". When marked as invalid,
// it will get a red background until it is focused.
/** Line edit that can be marked as "invalid" to show input validation feedback. When marked as invalid,
it will get a red background until it is focused.
*/
class QValidatedLineEdit : public QLineEdit
{
Q_OBJECT

View file

@ -3,19 +3,18 @@
#include <QComboBox>
// QComboBox that can be used with QDataWidgetMapper to select
// ordinal values from a model.
/* QComboBox that can be used with QDataWidgetMapper to select ordinal values from a model. */
class QValueComboBox : public QComboBox
{
Q_OBJECT
Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged USER true);
Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged USER true)
public:
explicit QValueComboBox(QWidget *parent = 0);
int value() const;
void setValue(int value);
// Model role to use as value
/** Specify model role to use as ordinal value */
void setRole(int role);
signals:

View file

@ -14,6 +14,7 @@ QT_BEGIN_NAMESPACE
class QUrl;
QT_END_NAMESPACE
/** Dialog for sending bitcoins */
class SendCoinsDialog : public QDialog
{
Q_OBJECT
@ -24,8 +25,8 @@ public:
void setModel(WalletModel *model);
// Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907)
// Hence we have to set it up manually
/** Set up the tab chain manually, as Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907).
*/
QWidget *setupTabChain(QWidget *prev);
void pasteEntry(const SendCoinsRecipient &rv);

View file

@ -9,6 +9,7 @@ namespace Ui {
class WalletModel;
class SendCoinsRecipient;
/** A single entry in the dialog for sending bitcoins. */
class SendCoinsEntry : public QFrame
{
Q_OBJECT
@ -21,13 +22,13 @@ public:
bool validate();
SendCoinsRecipient getValue();
// Return true if the entry is still empty and unedited
/** Return whether the entry is still empty and unedited */
bool isClear();
void setValue(const SendCoinsRecipient &value);
// Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907)
// Hence we have to set it up manually
/** Set up the tab chain manually, as Qt messes up the tab chain by default in some cases (issue http://bugreports.qt.nokia.com/browse/QTBUG-10907).
*/
QWidget *setupTabChain(QWidget *prev);
public slots:

View file

@ -8,11 +8,12 @@
class CWallet;
class CWalletTx;
/** Provide a human-readable extended HTML description of a transaction.
*/
class TransactionDesc: public QObject
{
Q_OBJECT
public:
// Provide human-readable extended HTML description of a transaction
static QString toHTML(CWallet *wallet, CWalletTx &wtx);
private:
TransactionDesc() {}

View file

@ -10,6 +10,7 @@ QT_BEGIN_NAMESPACE
class QModelIndex;
QT_END_NAMESPACE
/** Dialog showing transaction details. */
class TransactionDescDialog : public QDialog
{
Q_OBJECT

View file

@ -4,29 +4,31 @@
#include <QSortFilterProxyModel>
#include <QDateTime>
// Filter transaction list according to pre-specified rules
/** Filter the transaction list according to pre-specified rules. */
class TransactionFilterProxy : public QSortFilterProxyModel
{
Q_OBJECT
public:
explicit TransactionFilterProxy(QObject *parent = 0);
// Earliest date that can be represented (far in the past)
/** Earliest date that can be represented (far in the past) */
static const QDateTime MIN_DATE;
// Last date that can be represented (far in the future)
/** Last date that can be represented (far in the future) */
static const QDateTime MAX_DATE;
// Type filter bit field (all types)
/** Type filter bit field (all types) */
static const quint32 ALL_TYPES = 0xFFFFFFFF;
static quint32 TYPE(int type) { return 1<<type; }
void setDateRange(const QDateTime &from, const QDateTime &to);
void setAddressPrefix(const QString &addrPrefix);
// Type filter takes a bitfield created with TYPE() or ALL_TYPES
/**
@note Type filter takes a bitfield created with TYPE() or ALL_TYPES
*/
void setTypeFilter(quint32 modes);
void setMinAmount(qint64 minimum);
// Set maximum number of rows returned, -1 if unlimited
/** Set maximum number of rows returned, -1 if unlimited. */
void setLimit(int limit);
int rowCount(const QModelIndex &parent = QModelIndex()) const;

View file

@ -8,6 +8,8 @@
class CWallet;
class CWalletTx;
/** UI model for transaction status. The transaction status is the part of a transaction that will change over time.
*/
class TransactionStatus
{
public:
@ -20,7 +22,7 @@ public:
{
Immature,
Mature,
MaturesWarning, /* Will likely not mature because no nodes have confirmed */
MaturesWarning, /**< Transaction will likely not mature because no nodes have confirmed */
NotAccepted
};
@ -35,19 +37,26 @@ public:
bool confirmed;
std::string sortKey;
/* For "Generated" transactions */
/** @name Generated (mined) transactions
@{*/
Maturity maturity;
int matures_in;
/**@}*/
/* Reported status */
/** @name Reported status
@{*/
Status status;
int64 depth;
int64 open_for; /* Timestamp if status==OpenUntilDate, otherwise number of blocks */
int64 open_for; /**< Timestamp if status==OpenUntilDate, otherwise number of blocks */
/**@}*/
/* Current number of blocks (to know whether cached status is still valid. */
/** Current number of blocks (to know whether cached status is still valid) */
int cur_num_blocks;
};
/** UI model for a transaction. A core transaction can be represented by multiple UI transactions if it has
multiple outputs.
*/
class TransactionRecord
{
public:
@ -62,7 +71,7 @@ public:
SendToSelf
};
/* Number of confirmation needed for transaction */
/** Number of confirmation needed for transaction */
static const int NumConfirmations = 6;
TransactionRecord():
@ -84,33 +93,35 @@ public:
{
}
/* Decompose CWallet transaction to model transaction records.
/** Decompose CWallet transaction to model transaction records.
*/
static bool showTransaction(const CWalletTx &wtx);
static QList<TransactionRecord> decomposeTransaction(const CWallet *wallet, const CWalletTx &wtx);
/* Fixed */
/** @name Immutable transaction attributes
@{*/
uint256 hash;
int64 time;
Type type;
std::string address;
int64 debit;
int64 credit;
/**@}*/
/* Subtransaction index, for sort key */
/** Subtransaction index, for sort key */
int idx;
/* Status: can change with block chain update */
/** Status: can change with block chain update */
TransactionStatus status;
/* Return the unique identifier for this transaction (part) */
/** Return the unique identifier for this transaction (part) */
std::string getTxID();
/* Update status from wallet tx.
/** Update status from core wallet tx.
*/
void updateStatus(const CWalletTx &wtx);
/* Is a status update needed?
/** Return whether a status update is needed.
*/
bool statusUpdateNeeded();
};

View file

@ -9,6 +9,8 @@ class TransactionTablePriv;
class TransactionRecord;
class WalletModel;
/** UI model for the transaction table of a wallet.
*/
class TransactionTableModel : public QAbstractTableModel
{
Q_OBJECT
@ -16,36 +18,37 @@ public:
explicit TransactionTableModel(CWallet* wallet, WalletModel *parent = 0);
~TransactionTableModel();
enum {
enum ColumnIndex {
Status = 0,
Date = 1,
Type = 2,
ToAddress = 3,
Amount = 4
} ColumnIndex;
};
// Roles to get specific information from a transaction row
// These are independent of column
enum {
// Type of transaction
/** Roles to get specific information from a transaction row.
These are independent of column.
*/
enum RoleIndex {
/** Type of transaction */
TypeRole = Qt::UserRole,
// Date and time this transaction was created
/** Date and time this transaction was created */
DateRole,
// Long description (HTML format)
/** Long description (HTML format) */
LongDescriptionRole,
// Address of transaction
/** Address of transaction */
AddressRole,
// Label of address related to transaction
/** Label of address related to transaction */
LabelRole,
// Net amount of transaction
/** Net amount of transaction */
AmountRole,
// Unique identifier
/** Unique identifier */
TxIDRole,
// Is transaction confirmed?
/** Is transaction confirmed? */
ConfirmedRole,
// Formatted amount, without brackets when unconfirmed
/** Formatted amount, without brackets when unconfirmed */
FormattedAmountRole
} RoleIndex;
};
int rowCount(const QModelIndex &parent) const;
int columnCount(const QModelIndex &parent) const;

View file

@ -16,6 +16,9 @@ class QFrame;
class QDateTimeEdit;
QT_END_NAMESPACE
/** Widget showing the transaction list for a wallet, including a filter row.
Using the filter row, the user can view or export a subset of the transactions.
*/
class TransactionView : public QWidget
{
Q_OBJECT

View file

@ -16,7 +16,7 @@ struct SendCoinsRecipient
qint64 amount;
};
// Interface to Bitcoin wallet from Qt view code
/** Interface to Bitcoin wallet from Qt view code. */
class WalletModel : public QObject
{
Q_OBJECT