Browse Source

Improve documentation for UI classes

tags/v0.15.1
Wladimir J. van der Laan 10 years ago
parent
commit
af836ad588

+ 1
- 0
src/qt/aboutdialog.h View File

@@ -8,6 +8,7 @@ namespace Ui {
}
class ClientModel;

/** "About" dialog box */
class AboutDialog : public QDialog
{
Q_OBJECT

+ 4
- 2
src/qt/addressbookpage.h 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);

+ 16
- 11
src/qt/addresstablemodel.h 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.

+ 6
- 4
src/qt/askpassphrasedialog.h 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);

+ 1
- 1
src/qt/bitcoinaddressvalidator.h 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

+ 10
- 8
src/qt/bitcoinamountfield.h 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:

+ 28
- 19
src/qt/bitcoinunits.h 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
//! @name Static API
//! Unit conversion and formatting
///@{

//! Get list of units, for dropdown box
static QList<Unit> availableUnits();
// Is unit ID valid?
//! Is unit ID valid?
static bool valid(int unit);
// Short name
//! Short name
static QString name(int unit);
// Longer description
//! Longer description
static QString description(int unit);
// Number of satoshis / unit
//! Number of Satoshis (1e-8) per unit
static qint64 factor(int unit);
// Number of amount digits (to represent max number of coins)
//! Number of amount digits (to represent max number of coins)
static int amountDigits(int unit);
// Number of decimals left
//! Number of decimals left
static int decimals(int unit);
// Format as string
//! Format as string
static QString format(int unit, qint64 amount, bool plussign=false);
// Format as string (with unit)
//! Format as string (with unit)
static QString formatWithUnit(int unit, qint64 amount, bool plussign=false);
// Parse string to coin amount
//! Parse string to coin amount
static bool parse(int unit, const QString &value, qint64 *val_out);
///@}

/// AbstractListModel implementation
enum {
// Unit identifier
//! @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;
};

+ 5
- 5
src/qt/clientmodel.h 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:

+ 6
- 3
src/qt/csvmodelwriter.h 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:

+ 2
- 0
src/qt/editaddressdialog.h View File

@@ -12,6 +12,8 @@ namespace Ui {
}
class AddressTableModel;

/** Dialog for editing an address and associated information.
*/
class EditAddressDialog : public QDialog
{
Q_OBJECT

+ 2
- 0
src/qt/guiutil.h 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:

+ 2
- 0
src/qt/macdockiconhandler.h View File

@@ -8,6 +8,8 @@ class QIcon;
class QWidget;
class objc_object;

/** Macintosh-specific dock icon handler.
*/
class MacDockIconHandler : public QObject
{
Q_OBJECT

+ 2
- 3
src/qt/monitoreddatamapper.h 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
{

+ 18
- 17
src/qt/notificator.h 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;

+ 3
- 0
src/qt/optionsdialog.h 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;

+ 1
- 1
src/qt/optionsmodel.h 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

+ 1
- 0
src/qt/overviewpage.h View File

@@ -13,6 +13,7 @@ namespace Ui {
class WalletModel;
class TxViewDelegate;

/** Overview ("home") page widget */
class OverviewPage : public QWidget
{
Q_OBJECT

+ 3
- 2
src/qt/qvalidatedlineedit.h 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

+ 3
- 4
src/qt/qvaluecombobox.h 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:

+ 3
- 2
src/qt/sendcoinsdialog.h 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);

+ 4
- 3
src/qt/sendcoinsentry.h 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:

+ 2
- 1
src/qt/transactiondesc.h 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() {}

+ 1
- 0
src/qt/transactiondescdialog.h View File

@@ -10,6 +10,7 @@ QT_BEGIN_NAMESPACE
class QModelIndex;
QT_END_NAMESPACE

/** Dialog showing transaction details. */
class TransactionDescDialog : public QDialog
{
Q_OBJECT

+ 8
- 6
src/qt/transactionfilterproxy.h 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;

+ 24
- 13
src/qt/transactionrecord.h 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();
};

+ 18
- 15
src/qt/transactiontablemodel.h 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;

+ 3
- 0
src/qt/transactionview.h 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

+ 1
- 1
src/qt/walletmodel.h 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

Loading…
Cancel
Save