View source for Development/Client2GuiConversion


== Client 2 Gui Conversion Guide ==

This page is meant as a guide for converting old client 2 gui functionality over to the new system. Some of these steps are meant for clarity and to fit the new coding guidelines and thus can be skipped if one is tight on time. These will be marked as optional, although in all likely cases they should still be performed as long as they don't take much time to do so.

The intention of this conversion is to separate the game logic code from the abstracted gui code while retaining the base functionality and re-using as much code as possible.

Throughout this guide I will be using xfer_funds_dlg.h and .cpp as an example on how to convert the old logic functionality as it is a fairly simple class and will serve this purpose sufficiently.

[Optional] 1. Rename class to camel case and a name more fitting for a logic class rather than a gui class. If the previous name is convoluted it would be preferable to use something more clear.

''E.g. Change the class name from GuiDlgXferFunds to FundsTransferManager.''

2. Remove the inheritance " : public GuiWindow" and any another GuiWindow related inheritance or derivations unless they are central to the class's operation. This includes "virtual bool Load(const std::string &filename_)", although be sure to check for any important game-logic related code in "virtual bool Load(const std::string &filename_)", if it's only adding event handlers and storing pointers to gui elements then those can be safely removed, this functionality will be replaced by the signal system in the new gui design. In the case of GuiDlgXferFunds the entire function can be removed, just be sure to keep in mind the list of functions that it assigned event handling to as this may prove useful in the later stages of the conversion.

By now GuiDlgXferFunds's declaration should look like this:


''class FundsTransferManager
{
public:
	FundsTransferManager(irr::gui::IGUIElement* parent_);

	void Clear();

	long64 GetCredits() const;

private:
	irr::gui::IGUIEditBox *    m_credits;
};''

3. The constructor for most classes that inherit from GuiWindow will usually take a parent gui element or some other gui-related parameter. These should usually be discarded with certain logic-specific parameters considered on a case by case basis. In the case of GuiDlgXferFunds the constructor parameter can be removed. In the constructor the class will usually attempt to set it's "Name" instance variable and perform other gui-related functions. These should also be considered if they seem central to the logic's operation but in the case of GuiDlgXferFunds we can just remove all of that. This actually removes the need for a constructor in this particular case altogether.

By now GuiDlgXferFunds's declaration should look like this:

''class FundsTransferManager
{
public:
	void Clear();

	long64 GetCredits() const;

private:
	irr::gui::IGUIEditBox *    m_credits;
};''

4. Old gui-game-logic classes usually keep pointers to relevant elements so they can be easily accessed. The new system will send and receive signals instead and does not need to be aware of the actual gui elements. The instance variables for these can be removed also. Be careful to only remove gui related instance variable, usually marked as being in the "gui::" namespace.

By now GuiDlgXferFunds's declaration should look like this:

''class FundsTransferManager
{
public:
	void Clear();

	long64 GetCredits() const;
};''

5. Convert base functionality to work with the new signals system. This part is hard because it usually involves changing/refactorying other files/classes due to the old code's "immediate mode" nature, where as this new code is "signal" or "event" based. The difference in philosophy is that in the old code an action would be performed during an event and then the change in state would be read and transferred as a message.

For example GuiPropManage creates a GuiDlgXferFunds, waits for the ok button to be clicked and for it to return, validates the result to be EDR_OK and then retrieves the amount in credits the player would like to transfer from GuiDlgXferFunds before sending the message. In the new system GuiDlgXferFunds should create the network message and send it directly upon receiving the signal that the ok button was clicked. GuiDlgXferFunds will either query the value from the edit box element by accessing the element through the name/id of the element OR it will receive the value in the form of a signal sent by the textbox element (Will need to Dorth's opinion on the intended usage here).

 - To Be Continued -