Getting Started - Ravbug/wxWidgetsTemplate GitHub Wiki

Now that you've decided that you want to use this template, follow these instructions to get started using this template for your code.

1) Install the required software

The required software can be found here. You do not need to use wxFormBuilder to use this template, but using it is often much easier than hand-writing the GUI description code. Later steps in this guide use wxFormBuilder.

2) Download and set up the repository

You can get a copy of this template to use in your own app, in a few different ways:

  1. Download as zip (recommended)
  2. Git clone, and delete the .git folder
  3. Fork this repository (if you want to keep up with updates to this template)

Any of these works methods work. However, do not use GitHub's create from template feature! Doing so will break all of the permissions on all of the scripts, leading to massive headache later.

Once you have your copy of the repository, delete README.md, or update it with your information.

3) Compile and test the sample app

Follow the instructions on Building the projects for your platform to confirm that the library and the sample app compiles successfully and correctly. The sample app will look something like this:

Sample app

If you get compiler errors or the app does not launch successfully, try a different method of downloading the repository. If all the methods fail, submit an issue here.

4) Edit the interface in wxFormBuilder

Inside the source folder there is a file named form.fpb. Open it in wxFormBuilder, and edit the UI by adding, changing, or removing elements. Press the F8 key (or go to File -> Generate Code), to generate new interface.h and interface.cpp. Do not edit these files by hand, because any edits you make will be lost when you generate new code.

If you want to add actions to your elements, define an ID for each control by opening the Properties sidebar, then typing a name for it. You can use one of the wxWidgets stock IDs, or write a custom name.

For this guide, create a single Button, and give it the ID YOUR_CONTROL_ID.

5) Add some functionality to your interface

Once you have edited the interface, open interface_derived.h and add a new private void member to MainFrame. Example:

// interface_derived.h

class MainFrame : public MainFrameBase
{
public:
	MainFrame(wxWindow* parent = NULL);
private:
	void OnHello(wxCommandEvent& event);
	void OnExit(wxCommandEvent& event);
	void OnAbout(wxCommandEvent& event);
        void OnMyButton(wxCommandEvent& event);    //Your custom event, not all events are command events
	wxDECLARE_EVENT_TABLE();
};

Then, open interface_derived.cpp and add a listing in the Event table. Example:

// interface_derived.cpp

//Declare event mapping here
wxBEGIN_EVENT_TABLE(MainFrame, wxFrame)
EVT_MENU(ID_Hello,   MainFrame::OnHello)
EVT_MENU(wxID_EXIT,  MainFrame::OnExit)
EVT_MENU(wxID_ABOUT, MainFrame::OnAbout)
EVT_BUTTON(YOUR_CONTROL_ID, MainFrame::OnMyButton)   //Your custom event's mapping
wxEND_EVENT_TABLE()

Finally, write the implementation of your function somewhere in interface_derived.cpp (or elsewhere, if you #include that file). This example summons a simple dialog box:

// interface_derived.cpp

void MainFrame:: OnMyButton(wxCommandEvent& event)
{
	wxLogMessage("Your message here! From OnMyButton.");
}

6) (optional) Add more files

You are not constrained to using the files this repo provides. You can use any external library, or add any other file that you want. Keep the following things in mind:

  1. Do not hand-edit interface.h or interface.cpp. I already mentioned this, and you might feel the urge to, but don't do it! If wxFormBuilder does not expose a setting you need, you can hand-enter that change into the derived class's constructor, in interface_derived.cpp.
  2. The Linux build tool automatically compiles all of the source files present in the source folder. If you do not want the contents of a file included on Linux, exclude it by simply surround the file's contents with:
#if !defined __linux__
//your code in here
#endif
  1. Place all of your source files in the source folder. Don't exclude files on Linux by placing them outside the source folder.
  2. On macOS and Windows, only the files included in the IDE's project will be compiled. If you were programing on Linux, and you bring your repository to a Mac or PC to compile it, make sure to add any missing files to the IDE's project.

7) Create a git repository

The .gitignore file has been set up for you. Simply run git init in the terminal, followed by git status to check your repository. You can include the Visual Studio or Xcode user data files in your repository if you like, however I advise against it.

Then run git add . followed by git commit -a -m "Initial commit" to create your first commit.

This repository is portable (if you aren't linking an external wxWidgets). You can take the folder and copy it to another computer or a network drive, and it will work.

8) ??? Profit??

Now that the project is set up, start writing your app! Read the wxWidgets License for information about publishing your app.

In addition, you may credit this repo if you like, but you don't have to. Please provide any feedback about the repository, this Wiki, or other non-wxWidgets related things in this repo's Issues section.