[ Lit Window Library at SourceForge ]  [ Lit Window Productions Homepage ]  [ wxWidgets Tips&Tricks ]  [  wxVisualSetup ]

RSS Reader Tutorial Step 1: Creating a UI prototype

The first step in the tutorial sets up the project, creates a window layout and builds and runs the basic program fragments for the first time.

Skip to RSS Reader Tutorial Step 3: Adding RapidUI if you

• know all about setting up wxWidgets projects
• only want to read about RapidUI details but don't actually want to write the RSS Reader.

This tutorial uses wxWidgets 2.5. If you haven't installed it already, please download it from http://www.wxwidgets.org and install it.

You will also need DialogBlocks from http://www.anthemion.co.uk/dialogblocks. DialogBlocks is a commercial Dialog designer, but the free, unregistered version suffices for this tutorial.

Creating a Visual Studio Project

This section walks you through the steps of creating a project file for Visual Studio .NET 2003. Most of the steps apply to other versions of Visual Studio as well. I will keep this section very brief, since I assume you have some knowledge of the Visual Studio IDE.

Creating the project and adding files

1. Start Visual Studio, create a new "Win32" project (not a "Win32 Console" project).
2. For precompiled headers, create a new file stdwx.cpp and add it to the project. Copy the following lines to it:

   #include "stdwx.h"
   

3. Open the "Properties" for this file and select C++|Precompiled Headers in the dialog. Select "All Configurations" from "Configuration" combobox in the upper left corner. If you forget this you will have to redo the changes for a "Release Build". Change the following properties:
   • Set "Create/Use precompiled header" to "Create Precompiled Header"
   • Set "Create/Use PCH file through" to "stdwx.h"
4. Add another file stdwx.h, add it to the project and copy the following lines to it:

   #pragma once
   #pragma warning(disable:4786)
   #include <wx/wxprec.h>
   
   // TODO: reference additional headers your program requires here
   
   #ifdef _DEBUG
   #define DEBUG_NEW new(_NORMAL_BLOCK, __FILE__, __LINE__)
   #include <crtdbg.h>
   #else
   #define DEBUG_NEW new
   #endif
   

5. Open the project properties and select C++|Precompiled headers from the category. You are going to change the default precompiled settings for the project, so that any files you add hereafter will use the new settings. Select "All Configurations" from the "Configuration" combobox. Change the following properties:
   • Set "Create/Use precompiled header" to "Use Precompiled Header"
   • Set "Create/Use PCH file through" to "stdwx.h"
6. Set up the libraries neccessary for wxWidgets. If you don't want to add them to the linker settings, you can also copy the following lines into stdwx.cpp:

   #include "stdwx.h"
   
   #ifndef __WIN95__
   #error An error in wxWindows version 2.4.0 and 2.4.1 require that you set WINVER=0x400 in the project settings!
           // To set WINVER, open the project properties page, then
           // locate C++ | Preprocessor | Preprocessor Definitions
           // and add ;WINVER=0x400 to the line.
   #endif
   
   // TODO: reference any additional headers you need in STDAFX.H
   // and not in this file
   #include "litwindow/wx/wxWidgetImport.h"
   

   Now all you have to do is set the correct "additional library path" in the linker settings. Make sure you get the right one, depending on wether you are using wxWidgets as a static library or as a DLL.
7. Set up the neccessary preprocessor defines. If you are using wxWidgets and the Lit Window Library as DLLs, you must define WXUSINGDLL and USINGDLL in the preprocessor settings. Remember to make these settings for both, the Debug and Release configuration.

Using DialogBlocks for the basic layout.

In this section you will be using DialogBlocks to create the basic window layout as described above.

Creating the frame window

1. Start DialogBlocks and create a new project file (*.pjd).
2. The Wizard will ask you for information about your dialog. Don't create the dialog, but cancel the Wizard instead.
3. Choose Element | Add Frame and insert a new frame window. This is going to be our main window. Name the class RssMainFrame.

Creating the layout.

1. Add a wxSplitterWindow to the frame. This splitter shall contain the Channels listbox in the left pane.
2. Add a wxListBox. This is going to be the Channels listbox.
3. Change the name of this listbox in the "Id Name" field from ID_LISTBOX to m_channelsList.
4. Add another wxSplitterWindow. This splitter window will appear to the right of the listbox and it shall contain the headlines list and the news item.
5. Change the orientation (DialogBlocks field "Orientation") of this splitter window to vertical.
6. Add a wxListBox. This is going to be the Headlines listbox.
7. Change the name of the listbox to m_headlinesList.
8. Add (from the Window submenu) a wxHtmlWindow. This window will contain the selected news item.
9. Change the name of the wxHtmlWindow to m_newsItem.

Adding a menubar

1. Add a wxMenuBar (Elements|Menu|wxMenuBar) to the frame.
2. Select the menubar and add a "menu" to the menubar.
   • Enter &File as the label of the menu.
3. Select the menu and add a menu item to it.
   • Enter E&xit as the label of the menu item.
   • Enter wxID_EXIT as the "Id name". DialogBlocks recognizes this name and updates the "Id value" automatically.

The basic layout is done.

Generating some code.

DialogBlocks creates the neccessary code for us. To use it with RapidUI you need to use the XRC resource scheme.

1. Open the Settings dialog (View|Settings) and select the "XRC Generation" category.
2. Check "Generate C++ for using XRC".
3. Enter "simple_rssreader.xrc" in the file name field.
4. "Save" the project. This will generate "rssmainframe.cpp", "rssmainframe.h" and "simple_rssreader.xrc" in the same directory.
5. Add these files to the Visual Studio project.

Make Visual Studio compile simple_rssreader.xrc automatically.

This short section covers the settings you have to make so that Visual Studio can automatically compile the *.xrc resource files. This tutorial uses wxrc.exe to create cpp code from an XRC file. To avoid further hassle with precompiled header and other settings, I #include the code generated by wxrc.exe in a standard .cpp file rather than use the generated file directly.

1. Compile the program "wxrc.exe" from the wxWidgets contrib/utils/wxrc folder. Use the Release build. This will create the file wxrc.exe in a vc_msw subdirectory. wxrc.exe is the resource compiler for XRC files and generates binary or .cpp files from a resource .xrc file.
2. In the tutorial project, open the properties for the file simple_rssreader.xrc
3. Enter the following in "Custom Build Step|General|Command Line". This command tells Visual Studio to execute wxrc.exe to compile the resource file.

   "$(WXWIN)\contrib\utils\wxrc\vc_msw\wxrc.exe" /c /o"$(InputDir)$(InputName)_xrc.inl" "$(InputPath)"

4. In the "Description" field, enter

   "Compiling XRC Resources..."

5. In the "Outputs" field, enter

   "$(InputDir)$(InputName)_xrc.inl"

6. Create and add a new .cpp file: simple_rssreader_xrc.cpp
7. Add the following lines to this file:

   #include "stdwx.h"
   #include "simple_rssreader_xrc.inl"
   

   This last step includes the wxrc.exe output in a .cpp file. This is just personal preference, because I find it easier this way than to use the wxrc.exe output directly and fiddle with the (precompiled) settings until everything works.

Deriving a class from wxApp

So far we have got

• a project file
• layout and code for the main window
• an XRC resource file

To run the program for the first time, we still need to derive a "main" class from wxApp, instantiate it and create the MainFrame in the OnInit function.

1. Add a new file simple_rssreader_app.cpp and copy these lines into it:

   #include "stdwx.h"
   #include "simple_rssreader_app.h"
   #define new DEBUG_NEW   // for debug memory management
   using namespace litwindow;
   //
   extern void InitXmlResource();  // created by wxrc.exe
   //
   void wx_printer(const char *l)
   {
       wxLogDebug(l);
   }
   litwindow::static_redirect_streambuf wx_redirect(wx_printer);
   //
   bool SimpleRssReader::OnInit()
   {
           wxXmlResource::Get()->InitAllHandlers();
           InitXmlResource();
           RssMainFrame *theFrame=new RssMainFrame(0);
           SetTopWindow(theFrame);
           theFrame->Show();
           return true;
       }
       catch (std::runtime_error &e) {
           wxLogError("std::runtime_error: %s", e.what());
       }
       return false;
   }
   IMPLEMENT_APP(SimpleRssReader)
   

2. Add a new file simple_rssreader_app.h and copy these lines into it:

   /* 
    * Copyright 2004, Hajo Kirchhoff - Lit Window Productions, http://www.litwindow.com
    * This file is part of the Lit Window Library. All use of this material - copying
    * in full or part, including in other works, using in non-profit or for-profit work
    * and other uses - is governed by the licence contained in the Lit Window Library 
    * distribution, file LICENCE.TXT
    * $Id: simple_rssreader_app.h,v 1.1.1.1 2004/10/04 06:41:13 hajokirchhoff Exp $
    */
   #pragma once
   class SimpleRssReader:public wxApp
   {
   public:
       bool OnInit();
   };
   DECLARE_APP(SimpleRssReader)
   

3. Open rssmainframe.cpp and insert the following #include statement at the top of the file.

   #include "stdwx.h"
   

   This enabled precompiled headers for this file.

   Note:

   This file has been generated automatically, but DialogBlocks is smart enough to recognize this change and will keep it next time it generates the file.

Adding a .RC file and Windows XP manifest.

Under Windows you need a .rc file and a Windows XP "manifest" if you want to enable XP's visual enhancements for the program.

1. Create a new text file and add the following lines to it:

   //{{NO_DEPENDENCIES}}
   #ifdef APSTUDIO_INVOKED
   #pragma error This file is not editable by Visual Studio
   #else
   #include <wx/msw/wx.rc>
   #endif
   

2. Save the file as simple_rssreader.rc.
3. Open the properties for this file and add the following include directory to All Configurations:

   $(WXWIN)\include

The line

//{{NO_DEPENDENCIES}}

tells Visual Studio to ignore any dependencies of this file when checking for modified files. If you omit this line, Visual Studio will ask if you want to build the application everytime you press F5, because it does not recognize that the dependend file wx/msw/wx.rc has not changed.

The remaining files simply include "wx/msw/wx.rc", which contains prebuild wxWidgets resources and a Windows XP manifest.

Building and running the program

1. Build the solution. If you get linker errors, make sure you have
   • set the correct preprocessor defines: WXUSINGDLL, USINGDLL - if you are using the DLL version
   • set the correct linker input path: $(WXWIN)\lib\vc_dll - if you are using the DLL version
   • specified the wx libraries, either directly in the linker tab or by adding the #pragma comment statements (see above)
2. Run the program.

Simple RSS Reader application, Step 1

This is what the result should look like.

Continue with RSS Reader Tutorial Step 2: Adding data structures, defining data adapters

---

Copyright 2004, Hajo Kirchhoff, Lit Window Productions