wxMax - Connecting to Events

Since events are quite an important part of a GUI system, it probably wants a little bit written about how to use them in wxMax :-)

The Connect(), ConnectAny() and ConnectRange() methods

These three methods are the keys to hooking up your application to wxMax's event framework.

Each works slightly differently, but they all share the common purpose of allowing you to provide a callback function to which a particular event will be passed.

Here are the APIs :

Method ConnectAny(eventType:Int, callback(event:wxEvent), userData:Object = Null, ..
		sink:wxEvtHandler = Null)

Method Connect(id:Int = -1, eventType:Int, callback(event:wxEvent), userData:Object = Null, ..
		sink:wxEvtHandler = Null)

Method ConnectRange(id:Int, lastId:Int, eventType:Int, callback(event:wxEvent), userData:Object = Null, ..
		sink:wxEvtHandler = Null)

The eventType parameter defines what type of event you are interested in catching. Each control can define its own events, as well as having the ability to raise events common amongst the rest. Typical event types might be, wxEVT_COMMAND_BUTTON_CLICKED (for a wxButton), wxEVT_COMMAND_TEXT_UPDATED (the result of typing into a wxTextCtrl) and wxEVT_ENTER_WINDOW (the mouse moving into a control).

Any given control can be connected to many events.

Controls in wxMax can have a unique ID attached to them when they are created, which can be used by you to specify interest in a particular control.

ConnectAny doesn't include an ID parameter as it is designed to basically work for any controls that raise the event.
Connect and ConnectRange specify the contol ID to monitor, with the latter also giving the last-ID in a range of controls which it will catch events for. Ranges are useful for handling events generated by Menus or Toolbars, where it is common to have the items in a numeric sequence.

The callback is a function pointer to a function taking a wxEvent object as a parameter. The wxEvent object can then be cast to the appropriate "real" event, so to acquire specific information.

With userData, you can supply an Object that will be passed back with the event in the wxEvent object.

Finally, sink allows you to do some more advanced event handling, by specifying a different wxEvtHandler to own the event. Normally not required.


As a small example, we're now going to take a look at the minimal sample, and examine how it connects to the Quit menu item.

In the sample, the menu item is created like so

		fileMenu.Append(wxID_EXIT, "&Quit~tAlt-Q", "Quit this program")

The parameter wxID_EXIT is a special unique ID for this particular purpose (on Mac, you need to use this ID to allow the Quit menu item to be placed in the proper application menu). By specifying an ID, we allow ourselves the luxury of connecting an event to that menu item. Otherwise, how would we know what menu item we'd clicked on?

		Connect(wxID_EXIT, wxEVT_COMMAND_MENU_SELECTED, OnQuit)

Here we are connecting a wxEVT_COMMAND_MENU_SELECTED event type to the ID. When the event is raised, it will call our function OnQuit(event:wxEvent) :

	Function OnQuit(event:wxEvent)
		' true is to force the frame to close
		wxWindow(event.parent).Close(True)
	End Function

..which closes the window (and since this is our only window, automagically quits the application too!).

As you can see, with the event framework, it's just a case of connecting a particular event to a control and a callback function.

:o)

Nice, is there a place where we can find all the event type/style constants? I'm currently searching the wxwidgets website, looks through most of the docs, but they only supply little bits and peices, and in the case of window styles, I cant find any.



Edit:
I've found something... still looking for styles/event types...
http://www.wxwidgets.org/manuals/stable/wx_stdevtid.html#stdevtid

but i don't see "wxEVT_COMMAND_MENU_SELECTED" on this list, so it must be something else..

Any ideas on the constants?

BlitzMax/mod/wx.mod/wx.mod/consts.bmx

alright found window styles:

WINDOW STYLES

wxSIMPLE_BORDER  Displays a thin border around the window. wxBORDER is the old name for this style.  

wxDOUBLE_BORDER  Displays a double border. Windows and Mac only.  

wxSUNKEN_BORDER  Displays a sunken border.  

wxRAISED_BORDER  Displays a raised border.  

wxSTATIC_BORDER  Displays a border suitable for a static control. Windows only.  

wxNO_BORDER  Displays no border, overriding the default border style for the window.  

wxTRANSPARENT_WINDOW  The window is transparent, that is, it will not receive paint events. Windows only. 
 
wxTAB_TRAVERSAL  Use this to enable tab traversal for non-dialog windows.  

wxWANTS_CHARS  Use this to indicate that the window wants to get all char/key events for all keys - even for keys like TAB or ENTER which are usually used for dialog navigation and which wouldn't be generated without this style. If you need to use this style in order to get the arrows or etc., but would still like to have normal keyboard navigation take place, you should create and send a wxNavigationKeyEvent in response to the key events for Tab and Shift-Tab.  

wxNO_FULL_REPAINT_ON_RESIZE  On Windows, this style used to disable repainting the window completely when its size is changed. Since this behaviour is now the default, the style is now obsolete and no longer has an effect.  

wxVSCROLL  Use this style to enable a vertical scrollbar.  

wxHSCROLL  Use this style to enable a horizontal scrollbar.  

wxALWAYS_SHOW_SB  If a window has scrollbars, disable them instead of hiding them when they are not needed (i.e. when the size of the window is big enough to not require the scrollbars to navigate it). This style is currently only implemented for wxMSW and wxUniversal and does nothing on the other platforms.  

wxCLIP_CHILDREN  Use this style to eliminate flicker caused by the background being repainted, then children being painted over them. Windows only.  

wxFULL_REPAINT_ON_RESIZE  Use this style to force a complete redraw of the window whenever it is resized instead of redrawing just the part of the window affected by resizing. Note that this was the behaviour by default before 2.5.1 release and that if you experience redraw problems with code which previously used to work you may want to try this. Currently this style applies on GTK+ 2 and Windows only, and full repainting is always done on other platforms.  

EXTRA WINDOW STYLES

wxWS_EX_VALIDATE_RECURSIVELY  By default, Validate/TransferDataTo/FromWindow() only work on direct children of the window (compatible behaviour). Set this flag to make them recursively descend into all subwindows.  

wxWS_EX_BLOCK_EVENTS  wxCommandEvents and the objects of the derived classes are forwarded to the parent window and so on recursively by default. Using this flag for the given window allows to block this propagation at this window, i.e. prevent the events from being propagated further upwards. Dialogs have this flag on by default.  

wxWS_EX_TRANSIENT  Don't use this window as an implicit parent for the other windows: this must be used with transient windows as otherwise there is the risk of creating a dialog/frame with this window as a parent which would lead to a crash if the parent is destroyed before the child.  

wxWS_EX_PROCESS_IDLE  This window should always process idle events, even if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. 

wxWS_EX_PROCESS_UI_UPDATES  This window should always process UI update events, even if the mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED. 

more info on windows:
http://www.wxwidgets.org/manuals/2.6/wx_wxwindow.html#wxwindow

that works too David.


And heres a constant for reference:

Standard window minus user's ability to resize

	Const wxDEFAULT_NO_RESIZE:Int = wxSYSTEM_MENU | wxMINIMIZE_BOX | ..
	wxMAXIMIZE_BOX | wxCLOSE_BOX | wxCAPTION | wxCLIP_CHILDREN | wxBORDER_STATIC

if you use wxFormBuilder i think they are shown in there too.
then use wxCodeGen (tools section of wxmod) to generate the code.
being more of a beginner i find thiese tools invaluable

Cheers
Glenn

Didnt really get form builder, confused the crap out of me :D

I'd rather learn the code to be honest..

Anyways, i've been searching, i'm still looking for a full list of event types... that const file david linked is missing some..

like for example "wxEVT_COMMAND_BUTTON_CLICKED"

I'm note sure a complete one's been compiled for wxMax yet.

What I usually do when learning about a new widget is search for it in the wxWidgetProgramming pdf, which usually lists all relevant events for the widget in question.

You'll find wxEVT_COMMAND_BUTTON_CLICKED in the wxButton stuff ;-)

As I've mentioned before, the docs still need a lot of work, but since it's not officially been released yet... :-p

Events for controls should be mentioned in the Type descriptions, really. I'll get there.