|
1 |
| -This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross-platform framework [Qt](https://www1.qt.io/developers/). |
| 1 | +This directory contains the source code for the Bitcoin Core graphical user interface (GUI). It uses the [Qt](https://www1.qt.io/developers/) cross-platform framework. |
2 | 2 |
|
3 | 3 | The current precise version for Qt 5 is specified in [qt.mk](/depends/packages/qt.mk).
|
4 | 4 |
|
5 | 5 | ## Compile and run
|
6 | 6 |
|
7 |
| -See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). |
| 7 | +See build instructions: [Unix](/doc/build-unix.md), [macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [FreeBSD](/doc/build-freebsd.md), [NetBSD](/doc/build-netbsd.md), [OpenBSD](/doc/build-openbsd.md) |
| 8 | + |
| 9 | +When following your systems build instructions, make sure to install the `Qt` dependencies. |
8 | 10 |
|
9 | 11 | To run:
|
10 | 12 |
|
11 | 13 | ```sh
|
12 | 14 | ./src/qt/bitcoin-qt
|
13 | 15 | ```
|
14 | 16 |
|
15 |
| -## Files and directories |
16 |
| - |
17 |
| -### forms |
| 17 | +## Files and Directories |
18 | 18 |
|
19 |
| -Contains [Designer UI](https://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. They are created with [Qt Creator](#using-qt-creator-as-ide), but can be edited using any text editor. |
| 19 | +#### forms/ |
20 | 20 |
|
21 |
| -### locale |
| 21 | +- A directory that contains [Designer UI](https://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. These files specify the characteristics of form elements in XML. Qt UI files can be edited with [Qt Creator](#using-qt-creator-as-ide) or using any text editor. |
22 | 22 |
|
23 |
| -Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md). |
| 23 | +#### locale/ |
24 | 24 |
|
25 |
| -### res |
| 25 | +- Contains translations. They are periodically updated and an effort is made to support as many languages as possible. The process of contributing translations is described in [doc/translation_process.md](/doc/translation_process.md). |
26 | 26 |
|
27 |
| -Resources such as the icon. |
| 27 | +#### res/ |
28 | 28 |
|
29 |
| -### test |
| 29 | + - Contains graphical resources used to enhance the UI experience. |
30 | 30 |
|
31 |
| -Tests. |
| 31 | +#### test/ |
32 | 32 |
|
33 |
| -### bitcoingui.(h/cpp) |
| 33 | +- Functional tests used to ensure proper functionality of the GUI. Significant changes to the GUI code normally require new or updated tests. |
34 | 34 |
|
35 |
| -Represents the main window of the Bitcoin UI. |
| 35 | +#### bitcoingui.(h/cpp) |
36 | 36 |
|
37 |
| -### \*model.(h/cpp) |
| 37 | +- Represents the main window of the Bitcoin UI. |
38 | 38 |
|
39 |
| -The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](https://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other Qt classes like [QValidator](https://doc.qt.io/qt-5/qvalidator.html). |
| 39 | +#### \*model.(h/cpp) |
40 | 40 |
|
41 |
| -ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`. |
| 41 | +- The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](https://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other Qt classes like [QValidator](https://doc.qt.io/qt-5/qvalidator.html). |
| 42 | +- ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`. |
42 | 43 |
|
43 |
| -### \*page.(h/cpp) |
| 44 | +#### \*page.(h/cpp) |
44 | 45 |
|
45 |
| -A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`. |
| 46 | +- A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`. |
46 | 47 |
|
47 |
| -### \*dialog.(h/cpp) |
| 48 | +#### \*dialog.(h/cpp) |
48 | 49 |
|
49 |
| -Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html). |
| 50 | +- Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html). |
50 | 51 |
|
51 |
| -### paymentserver.(h/cpp) |
| 52 | +#### paymentserver.(h/cpp) |
52 | 53 |
|
53 |
| -Used to process BIP21 payment URI requests. Also handles URI based application switching (e.g. when following a bitcoin:... link from a browser). |
| 54 | +- (Deprecated) Used to process BIP21 payment URI requests. Also handles URI-based application switching (e.g. when following a bitcoin:... link from a browser). |
54 | 55 |
|
55 |
| -### walletview.(h/cpp) |
| 56 | +#### walletview.(h/cpp) |
56 | 57 |
|
57 |
| -Represents the view to a single wallet. |
| 58 | +- Represents the view to a single wallet. |
58 | 59 |
|
59 |
| -### Other .h/cpp files |
| 60 | +#### Other .h/cpp files |
60 | 61 |
|
61 | 62 | * UI elements like BitcoinAmountField, which inherit from QWidget.
|
62 | 63 | * `bitcoinstrings.cpp`: automatically generated
|
63 |
| -* `bitcoinunits.(h/cpp)`: BTC / mBTC / etc handling |
| 64 | +* `bitcoinunits.(h/cpp)`: BTC / mBTC / etc. handling |
64 | 65 | * `callback.h`
|
65 |
| -* `guiconstants.h`: UI colors, app name, etc |
| 66 | +* `guiconstants.h`: UI colors, app name, etc. |
66 | 67 | * `guiutil.h`: several helper functions
|
67 | 68 | * `macdockiconhandler.(h/mm)`: macOS dock icon handler
|
68 | 69 | * `macnotificationhandler.(h/mm)`: display notifications in macOS
|
69 | 70 |
|
70 | 71 | ## Contribute
|
71 | 72 |
|
72 |
| -See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for Qt: |
| 73 | +See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. |
| 74 | + |
| 75 | +**Note:** Do not change `local/bitcoin_en.ts`. It is updated [automatically](/doc/translation_process.md#writing-code-with-translations). |
| 76 | + |
| 77 | +## Using Qt Creator as an IDE |
| 78 | + |
| 79 | +[Qt Creator](https://www.qt.io/product/development-tools) is a powerful tool which packages a UI designer tool (Qt Designer) and a C++ IDE into one application. This is especially useful if you want to change the UI layout. |
| 80 | + |
| 81 | +#### Download Qt Creator |
| 82 | + |
| 83 | +On Unix and macOS, Qt Creator can be installed through your package manager. Alternatively, you can download a binary from the [Qt Website](https://www.qt.io/download/). |
| 84 | + |
| 85 | +**Note:** If installing from a binary grabbed from the Qt Website: During the installation process, uncheck everything except for `Qt Creator`. |
| 86 | + |
| 87 | +##### macOS |
| 88 | + |
| 89 | +```sh |
| 90 | +brew install qt-creator |
| 91 | +``` |
| 92 | + |
| 93 | +##### Ubuntu & Debian |
| 94 | + |
| 95 | +```sh |
| 96 | +sudo apt-get install qtcreator |
| 97 | +``` |
| 98 | + |
| 99 | +#### Setup Qt Creator |
73 | 100 |
|
74 |
| -* don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations) |
| 101 | +1. Make sure you've installed all dependencies specified in your systems build instructions |
| 102 | +2. Follow the compile instructions for your system, run `./configure` with the `--enable-debug` flag |
| 103 | +3. Start Qt Creator. At the start page, do: `New` -> `Import Project` -> `Import Existing Project` |
| 104 | +4. Enter `bitcoin-qt` as the Project Name and enter the absolute path to `src/qt` as Location |
| 105 | +5. Check over the file selection, you may need to select the `forms` directory (necessary if you intend to edit *.ui files) |
| 106 | +6. Confirm the `Summary` page |
| 107 | +7. In the `Projects` tab, select `Manage Kits...` |
75 | 108 |
|
76 |
| -## Using Qt Creator as IDE |
| 109 | + **macOS** |
| 110 | + - Under `Kits`: select the default "Desktop" kit |
| 111 | + - Under `Compilers`: select `"Clang (x86 64bit in /usr/bin)"` |
| 112 | + - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation) |
77 | 113 |
|
78 |
| -You can use Qt Creator as an IDE. This is especially useful if you want to change |
79 |
| -the UI layout. |
| 114 | + **Ubuntu & Debian** |
80 | 115 |
|
81 |
| -Download and install the community edition of [Qt Creator](https://www.qt.io/download/). |
82 |
| -Uncheck everything except Qt Creator during the installation process. |
| 116 | + Note: Some of these options may already be set |
83 | 117 |
|
84 |
| -Instructions for macOS: |
| 118 | + - Under `Kits`: select the default "Desktop" kit |
| 119 | + - Under `Compilers`: select `"GCC (x86 64bit in /usr/bin)"` |
| 120 | + - Under `Debuggers`: select `"GDB"` as debugger |
85 | 121 |
|
86 |
| -1. Make sure you installed everything through Homebrew mentioned in the [macOS build instructions](/doc/build-osx.md) |
87 |
| -2. Use `./configure` with the `--enable-debug` flag |
88 |
| -3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project |
89 |
| -4. Enter "bitcoin-qt" as project name, enter src/qt as location |
90 |
| -5. Leave the file selection as it is |
91 |
| -6. Confirm the "summary page" |
92 |
| -7. In the "Projects" tab select "Manage Kits..." |
93 |
| -8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler |
94 |
| -9. Select LLDB as debugger (you might need to set the path to your installation) |
95 |
| -10. Start debugging with Qt Creator (you might need to the executable to "bitcoin-qt" under "Run", which is where you can also add command line arguments) |
| 122 | +8. While in the `Projects` tab, ensure that you have the `bitcoin-qt` executable specified under `Run` |
| 123 | + - If the executable is not specified: click `"Choose..."`, navigate to `src/qt`, and select `bitcoin-qt` |
| 124 | +9. You're all set! Start developing, building, and debugging the Bitcoin Core GUI |
0 commit comments