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  
  3  The current precise version for Qt is specified in [qt_details.mk](/depends/packages/qt_details.mk).
  4  
  5  ## Compile and run
  6  
  7  See build instructions: [Unix](/doc/build-unix.md), [macOS](/doc/build-osx.md), [Windows](/doc/build-windows-msvc.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.
 10  
 11  To run:
 12  
 13  ```sh
 14  ./build/bin/bitcoin-qt
 15  ```
 16  
 17  ## Files and Directories
 18  
 19  #### forms/
 20  
 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  
 23  #### locale/
 24  
 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  
 27  #### res/
 28  
 29   - Contains graphical resources used to enhance the UI experience.
 30  
 31  #### test/
 32  
 33  - Functional tests used to ensure proper functionality of the GUI. Significant changes to the GUI code normally require new or updated tests.
 34  
 35  #### bitcoingui.(h/cpp)
 36  
 37  - Represents the main window of the Bitcoin UI.
 38  
 39  #### \*model.(h/cpp)
 40  
 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`.
 43  
 44  #### \*page.(h/cpp)
 45  
 46  - A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`.
 47  
 48  #### \*dialog.(h/cpp)
 49  
 50  - Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html).
 51  
 52  #### paymentserver.(h/cpp)
 53  
 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).
 55  
 56  #### walletview.(h/cpp)
 57  
 58  - Represents the view to a single wallet.
 59  
 60  #### Other .h/cpp files
 61  
 62  * UI elements like BitcoinAmountField, which inherit from QWidget.
 63  * `bitcoinstrings.cpp`: automatically generated
 64  * `bitcoinunits.(h/cpp)`: BTC / mBTC / etc. handling
 65  * `callback.h`
 66  * `guiconstants.h`: UI colors, app name, etc.
 67  * `guiutil.h`: several helper functions
 68  * `macdockiconhandler.(h/mm)`: macOS dock icon handler
 69  * `macnotificationhandler.(h/mm)`: display notifications in macOS
 70  
 71  ## Contribute
 72  
 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
100  
101  1. Make sure you've installed all dependencies specified in your systems build instructions
102  2. Follow the compile instructions for your system, adding the `-DCMAKE_BUILD_TYPE=Debug` build 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...`
108  
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)
113  
114   **Ubuntu & Debian**
115  
116   Note: Some of these options may already be set
117  
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
121  
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 `build/bin`, and select `bitcoin-qt`
124  9. You're all set! Start developing, building, and debugging the Bitcoin Core GUI