How does it work? /dig command

[acraig]

So I've been away for a while and I've forgotten how a lot of the code base works.   So I thought it might be interesting to document my process of how I go about figuring how stuff works again.  Since I like crafting and gathering I thought I would start with something like the /dig command.  Should be easy enough to figure out how that works. 

So to start off with... I know that the windows are defined by XML files that layout the widgets and graphics.  So I know that I can use the /dig command in the chat window so I start in /PlaneShift/PS/data/gui/chat.xml and look for things like input or edit or stuff like that.   Sure enough I find:

Code: [Select]

<widget name="InputText" factory="pawsEditTextBox" alwaysontop="yes">

So this is my first starting point in the code.  I need to look at pawsEditTextBox and see how it handles input.

[acraig]

Found pawsEditTextBox in  PlaneShift\PS\src\common\paws\pawstextbox.cpp  and pawsEditTextBox::OnKeyDown(...) looks like a good place to start. Since the /dig command ends with <Enter> this is probably the place to go.   So looking through this function there is stuff to handle the delete key, arrow keys, backspace, nothing to handle the enter key though yet.   It looks like it punts this back to the base pawsWidget class and calls the base pawsWidget::OnKeyDown instead.  So off to that class to see what it does.   

[acraig]

So now looking in the pawsWidget base class and it's OnKeyDown() to see what it is doing.   It handles the CSKEY_ENTER!.   All it does is hand it off to the parent widget  ( return parent->OnKeyDown(keyCode,key,modifiers) )

I know that the pawsChatWindow is the parent of the edittextbox so now taking a look inside the pawsChatWindow to see what is going on in there.

[LigH]

Only reading the title of the thread, I wondered how you could ask such a question ... but the post reveals that your focus is not where I expected it from the title alone. Interesting task you gave yourself. Well, I hope you will pass a function where the command is sent to the server.

[acraig]

So now inside the pawsChatWindow::OnKeyDown,  it handles the CSKEY_ENTER as well and calls a member function: SendChatLine() which in turn calls cmdsource->Publish(textToSend).

Looking at the pawsChatWindow header I can see that it inherits from psCmdBase which has the CmdHandler cmdsource.   So it's basically publishing this command to the CommandHandler to send out to its various subscribers. 

So the question becomes now where does this command handler get created?   By looking around a bit I can see that the psClient engine creates one main command handler.

\PlaneShift\PS\src\client\psnetmanager.cpp psNetManager::Initialize() is the actual place where it does 

Code: [Select]

cmdhandler = csPtr<CmdHandler> (new CmdHandler(object_reg));

This CmdHandler is then passed around to the various components on the client like the ChatWindow. For example when the pawsChatWindow is doing it's PostSetup it gets the CmdHandler from the psengine itself.

Code: [Select]

...
bool pawsChatWindow::PostSetup()
{
    if ( !psCmdBase::Setup( psengine->GetMsgHandler(), psengine->GetCmdHandler()) )
        return false;
...

So there is one global command handler that we publish stuff to.




Adding in a hacked together class diagram to get an idea of how the classes relate to each other.

[acraig]

Ok, so now the investigation is on the cmdhandler to see what sort of stuff relates to that.  I can see that there is also the psUserCommands ( which like the main command handler is owned by the psNetManager ).    When this psUserCommands object is created it "subscribes" to various commands

Code: [Select]

cmdsource->Subscribe("/dig",           this);

So basically "this" being the psUserCommands object will handle this /dig command when it gets it.

So what happens now is that when the ChatWindow does cmdsource->Publish(textToSend)  it will end up calling the psUserCommands::HandleCommand().     

So this is somewhat complex so I will try to diagram it out again to get an idea of how the command ends up getting to the psUserCommands::HandleCommand.

Updated Diagram:

[acraig]

Ok, so we last left off we were looking at the psUserCommands::HandleCommand to see how it handles the /dig that is subscribes to.  So looking through this function it has a case for /dig and builds up the network message to send to the server.

Code: [Select]

psWorkCmdMessage work(cmd);
work.SendMessage();

So taking a look at the psWorkCmdMessage definition I can see that this is a network message ( psWorkCmdMessage : public psMessageCracker ) that is used to send work commands to and from the server.

It has fields for the command, player, filter ( ie what we are 'digging' for ) and a repairSlotName ( which must be used elsewhere ).

The SendMessage command hands the data off to the static MsgHandler to be handled by the network (  msghandler->SendMessage(msg);  ).   I probably won't go into the details of the networking stuff because networking stuff is convoluted as it is.

But basically I now have a full path from keyboard entry, how it is passed around the GUI elements and how it ends up in the command handler and packaged up for delivery to the server.   

[verden]

I think you should be thankful to have yourself available to go through a narrative learning process in this manner. This is really an excellent thread, thanks for taking the time to write it up.