Events are integral part of every GUI application. All GUI applications are event-driven. An application reacts to different event types which are generated during it's life. Events are generated mainly by the user of an application. But they can be generated by other means as well. e.g. internet connection, window manager, timer. When the application starts a main loop is created. The application sits in the main loop and waits for the events to be generated. The main loop quits, when we exit the application.
Event is a piece of application-level information from the underlying framework, typically the GUI toolkit. Event loop is a programming construct that waits for and dispatches events or messages in a program. The event loop repeatedly looks for events to process them. A dispatcher is a process which maps events to event handlers. Event handlers are methods that react to events.
Event object is an object associated with the event. It is usually a window. Event type is a unique event, that has been generated.
We will talk about a move event. A move event holds information about move change events. A move event is generated, when we move a window to a new position. The class that represents the move event is wxMoveEvent. The wxEVT_MOVE is an event type.
move.bmx <- Open sourceSuperStrict Framework wx.wxApp Import wx.wxFrame Import wx.wxPanel Import wx.wxStaticText New MyApp.Run() Type MyApp Extends wxApp Method OnInit:Int() Local mv:Move = Move(New Move.Create(Null, wxID_ANY, .. "Move event", -1, -1, 250, 130)) mv.Show(True) Return True End Method End Type Type Move Extends wxFrame Field st1:wxStaticText Field st2:wxStaticText Method OnInit() Local panel:wxPanel = New wxPanel.Create(Self, -1) st1 = New wxStaticText.Create(panel, -1, "", 10, 10) st2 = New wxStaticText.Create(panel, -1, "", 10, 30) ConnectAny(wxEVT_MOVE, OnMove) Centre() End Method Function OnMove(event:wxEvent) Local m:Move = Move(event.parent) Local x:Int, y:Int wxMoveEvent(event).GetPosition(x, y) m.st1.SetLabel("x: " + x) m.st2.SetLabel("y: " + y) End Function End Type
The example displays the current position of the window.
Here we connect a wxEVT_MOVE event type with the OnMove() function.
Local width:Int, height:Int wxMoveEvent(event).GetPosition(width, height)
The event parameter in the OnMove() function is an object specific to a particular event. In our case it is the instance of a wxMoveEvent type. Due to limitations of BlitzMax, the parameter must be declared as a wxEvent type, which we can cast to the correct type. This object holds information about the event. We can find out the current position by calling the GetPosition() method of the event.
There are two types of events. Basic events and command events. They differ in propagation. Event propagation is travelling of events from child widgets to parent widgets and grand parent widgets etc. Basic events do not propagate. Command events do propagate. For example wxCloseEvent is a basic event. It does not make sense for this event to propagate to parent widgets.
By default, the event that is catched in a event handler stops propagating. To continue propagation, we must call the Skip() method.
In our example, we have a button on a panel. The panel is placed in a frame widget. We define a handler for all widgets.
event reached button type event reached panel type event reached frame type
We get this, when we click on the button. The event travels from the button to panel and to frame.
Try to omit some Skip() methods and see, what hapens.
Sometimes we need to stop processing an event. To do this, we call the method Veto().
In our example, we process a wxCloseEvent. This event is called, when we click the X button on the titlebar, press Alt + F4 or select close from the system menu. In many applications, we want to prevent from accidentally closing the window, if we made some changes. To do this, we must connect the wxEVT_CLOSE_WINDOW event type.
Local dial:wxMessageDialog = New wxMessageDialog.Create(Null, .. "Are you sure to quit?", "Question", .. wxYES_NO | wxNO_DEFAULT | wxICON_QUESTION)
During the close event, we show a message dialog.
If ret = wxID_YES Then wxWindow(event.parent).Destroy() Else wxCloseEvent(event).Veto() End If
Depending on the return value, we destroy the window, or veto the event. Notice that to close the window, we must call the Destroy() method. By calling the Close() method, we would end up in an endless cycle.
Window identifiers are integers that uniquely determine the window identity in the event system. There are three ways to create window id's.
Each widget has an id parameter. This is a unique number in the event system. If we work with multiple widgets, we must differantiate among them.
wxButton.Create(parent, -1) wxButton.Create(parent, wxID_ANY)
If we provide -1 or wxID_ANY for the id parameter, we let the wxWidgets automatically create an id for us. The automatically created id's are always negative, whereas user specified id's must always be positive. We usually use this option when we do not need to change the widget state. For example a static text, that will never be changed during the life of the application. We can still get the id, if we want. There is a method GetId(), which will determine the id for us.
Standard identifiers should be used whenever possible. The identifiers can provide some standard graphics or behaviour on some platforms.
In our example we use standard identifiers on buttons. On linux, the buttons have small icons.