Contents

Events

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.

Definitions

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.

A simple event example

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 source
SuperStrict 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.

ConnectAny(wxEVT_MOVE, OnMove)

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.


Move event
Figure: Move event

Event propagation

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.


SuperStrict
 
Framework wx.wxApp
Import wx.wxFrame
Import wx.wxPanel
Import wx.wxButton
Import BRL.StandardIO
 
Const ID_BUTTON:Int = 1

New MyApp.Run()
 
Type MyApp Extends wxApp

	Method OnInit:Int()
	
		Local prop:Propagate = Propagate(New Propagate.Create(Null, wxID_ANY, ..
			"Propagate", -1, -1, 250, 130))
		prop.Show(True)
 
		Return True
	End Method

End Type

Type Propagate Extends wxFrame
 
	Method OnInit()
		
		Local panel:MyPanel = MyPanel(New MyPanel.Create(Self, -1))
		
		New MyButton.Create(panel, ID_BUTTON, "Ok")
		
		Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, OnClick)
		
		Centre()
 
	End Method

	Function OnClick(event:wxEvent)
		Print "event reached frame type"
		event.Skip()
	End Function
	
End Type

Type MyButton Extends wxButton

	Method OnInit()
		Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, OnClick)
	End Method
	
	Function OnClick(event:wxEvent)
		Print "event reached button type"
		event.Skip()
	End Function
	
End Type

Type MyPanel Extends wxPanel

	Method OnInit()
		Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, OnClick)
	End Method

	Function OnClick(event:wxEvent)
		Print "event reached panel type"
		event.Skip()
	End Function

End Type

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.

Vetoing events

Sometimes we need to stop processing an event. To do this, we call the method Veto().


SuperStrict
 
Framework wx.wxApp
Import wx.wxFrame
Import wx.wxMessageDialog

New MyApp.Run()
 
Type MyApp Extends wxApp

	Method OnInit:Int()
	
		Local v:Veto = Veto(New Veto.Create(Null, wxID_ANY, ..
			"Veto", -1, -1, 250, 130))
		v.Show(True)
 
		Return True
	End Method

End Type

Type Veto Extends wxFrame
 
	Method OnInit()
		
		ConnectAny(wxEVT_CLOSE_WINDOW, OnClose)
		
		Centre()
 
	End Method
	
	Function OnClose(event:wxEvent)
		Local dial:wxMessageDialog = New wxMessageDialog.Create(Null, ..
			"Are you sure to quit?", "Question", ..
			wxYES_NO | wxNO_DEFAULT | wxICON_QUESTION)

		Local ret:Int = dial.ShowModal()
		dial.Free()

		If ret = wxID_YES Then
			wxWindow(event.parent).Destroy()
		Else
			wxCloseEvent(event).Veto()
		End If

	End Function

End Type

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

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.


SuperStrict
 
Framework wx.wxApp
Import wx.wxFrame
Import wx.wxPanel
Import wx.wxButton
 
New MyApp.Run()
 
Type MyApp Extends wxApp

	Method OnInit:Int()
	
		Local id:Ident = Ident(New Ident.Create(Null, wxID_ANY, ..
			"Identifiers", -1, -1, 200, 150))
		id.Show(True)
 
		Return True
	End Method

End Type

Type Ident Extends wxFrame
 
	Method OnInit()
		
		Local panel:wxPanel = New wxPanel.Create(Self, -1)
		
		Local grid:wxGridSizer = New wxGridSizer.Create(2, 3)
		
		grid.Add(New wxButton.Create(panel, wxID_CANCEL), 0, wxTOP | wxLEFT, 9)
		grid.Add(New wxButton.Create(panel, wxID_DELETE), 0, wxTOP, 9)
		grid.Add(New wxButton.Create(panel, wxID_SAVE), 0, wxLEFT, 9)
		grid.Add(New wxButton.Create(panel, wxID_EXIT))
		grid.Add(New wxButton.Create(panel, wxID_STOP), 0, wxLEFT, 9)
		grid.Add(New wxButton.Create(panel, wxID_NEW))
		
		panel.SetSizer(grid)
		Centre()
 
	End Method
	
End Type

In our example we use standard identifiers on buttons. On linux, the buttons have small icons.


Identifiers
Figure: Identifiers