---
id: brl.eventqueue
title: BRL.EventQueue
sidebar_label: BRL.EventQueue
---



The event queue is a simple first-in, first-out queue that is used to collect 
[TEvent](../../brl/brl.event/tevent) objects emitted by your application.

The [PollEvent](../../brl/brl.eventqueue/#function-polleventint) and [WaitEvent](../../brl/brl.eventqueue/#function-waiteventint) commands can be used to receive the next event from the event
queue, while the [PeekEvent](../../brl/brl.eventqueue/#function-peekeventtevent) command can be used to check if the event queue is empty.

Events are added to the event queue using [PostEvent](../../brl/brl.eventqueue/#function-posteventint-eventteventupdateintfalse-).


## Functions

### `Function PeekEvent:TEvent()`

Examine the next event in the event queue


[PeekEvent](../../brl/brl.eventqueue/#function-peekeventtevent) examines the next event in the event queue, without removing it from the
event queue or modifying the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable.

If there are no events in the event queue, [PeekEvent](../../brl/brl.eventqueue/#function-peekeventtevent) returns [Null](../../brl/brl.blitz/#null).


<br/>

### `Function PollEvent:Int()`

Get the next event from the event queue


[PollEvent](../../brl/brl.eventqueue/#function-polleventint) removes an event from the event queue and updates the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent)
global variable.

If there are no events in the event queue, [PollEvent](../../brl/brl.eventqueue/#function-polleventint) returns 0.


#### Returns
The id of the next event in the event queue, or 0 if the event queue is empty


<br/>

### `Function WaitEvent:Int()`

Get the next event from the event queue, waiting if necessary


[WaitEvent](../../brl/brl.eventqueue/#function-waiteventint) removes an event from the event queue and updates the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent)
global variable.

If there are no events in the event queue, [WaitEvent](../../brl/brl.eventqueue/#function-waiteventint) halts program execution until
an event is available.


#### Returns
The id of the next event in the event queue


<br/>

### `Function PostEvent:Int( event:TEvent,update:Int=False )`

Post an event to the event queue

[PostEvent](../../brl/brl.eventqueue/#function-posteventint-eventteventupdateintfalse-) adds an event to the end of the event queue.

The <b>update</b> flag can be used to update an existing event. If <b>update</b> is True
and an event with the same <b>id</b> and <b>source</b> is found in the event
queue, the existing event will be updated instead of <b>event</b>
being added to the event queue. This can be useful to prevent high frequency
events such as timer events from flooding the event queue.


<br/>

### `Function EventID:Int()`

Get current event id

#### Returns
The <b>id</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


#### Example 1
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local MyWindow:TGadget=CreateWindow("Button Example", 200,200,320,240)
Local MyButton:TGadget=CreateButton("Click Me",140,60,80,40, MyWindow)

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
   End Select
Forever
```
#### Example 2
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("events",0,0,320,240)

Local button:tgadget=CreateButton("Button1",4,4,80,24,window)
Local canvas:tgadget=CreateCanvas(84,4,80,24,window,1)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	Select EventID()
		Case EVENT_GADGETACTION Print "gadgetaction (buttonpress, etc.)"
		Case EVENT_MOUSEMOVE Print "canvas mousemove"
	End Select
	
Forever
```
<br/>

### `Function EventData:Int()`

Get current event data

#### Returns
The <b>data</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


#### Example
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("leftclick/rightclick",0,0,320,240)

Local canvas:tgadget=CreateCanvas(4,4,160,160,window,1)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	Select EventData()
		Case 1 Print "leftclick"
		Case 2 Print "rightclick"
	End Select
Forever
```
<br/>

### `Function EventMods:Int()`

Get current event modifiers

#### Returns
The <b>mods</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


<br/>

### `Function EventX:Int()`

Get current event x value

#### Returns
The <b>x</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


#### Example
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("move mouse",0,0,320,240)

Local canvas:tgadget=CreateCanvas(4,4,160,160,window,1)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	If EventID()=EVENT_MOUSEMOVE
		Print EventX()
	EndIf
Forever
```
<br/>

### `Function EventY:Int()`

Get current event y value

#### Returns
The <b>y</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


#### Example
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("move mouse",0,0,320,240)

Local canvas:tgadget=CreateCanvas(4,4,160,160,window,1)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	If EventID()=EVENT_MOUSEMOVE
		Print EventY()
	EndIf
Forever
```
<br/>

### `Function EventExtra:Object()`

Get current event extra value

#### Returns
The <b>extra</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


<br/>

### `Function EventText:String()`

Get current event extra value converted to a string

#### Returns
The <b>extra</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable converted to a string


#### Example
```blitzmax
'
' Drop a file onto the window to see EventText() return the path.
'
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("move mouse",0,0,320,240,Null,15|WINDOW_ACCEPTFILES)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	If EventID()=EVENT_WINDOWACCEPT
		Print EventText()
	EndIf
Forever
```
<br/>

### `Function EventSource:Object()`

Get current event source object

#### Returns
The <b>source</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable


#### Example 1
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local MyWindow:TGadget=CreateWindow("Two Buttons Example", 200,200,320,240)
Local Button1:TGadget=CreateButton("One",140,40,80,40, MyWindow)
Local Button2:TGadget=CreateButton("Two",140,100,80,40, MyWindow)

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
  Case EVENT_GADGETACTION
    Select EventSource()
      Case Button1
         SetGadgetText(Button1,"One clicked")
      Case Button2
         SetGadgetText(Button2,"Two clicked")
      End Select
   End Select
Forever
```
#### Example 2
```blitzmax
SuperStrict

Import MaxGUI.Drivers

Local window:tgadget=CreateWindow("events",0,0,320,240)

Local button1:tgadget=CreateButton("Button1",4,4,80,24,window)
Local button2:tgadget=CreateButton("Button2",84,4,80,24,window)

Repeat
	WaitEvent()
	If EventID()=EVENT_WINDOWCLOSE End
	
	Select EventSource()
		Case button1 Print "button1"
		Case button2 Print "button2"
	End Select
	
Forever
```
<br/>

### `Function EventSourceHandle:Size_T()`

Get current event source object handle

#### Returns
The <b>source</b> field of the [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable converted to an integer handle


<br/>

## Globals

### `Global CurrentEvent:TEvent=NullEvent`

Current Event

The [CurrentEvent](../../brl/brl.eventqueue/#global-currenteventteventnullevent) global variable contains the event most recently returned by
[PollEvent](../../brl/brl.eventqueue/#function-polleventint) or [WaitEvent](../../brl/brl.eventqueue/#function-waiteventint).


<br/>