Events

Author:: peterc (IP: 192.168.0.1)
Timestamp:: 12/20/07 11:57:09 (10 years ago)
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

documentation/RML/Events

v0	v1
	1	= RML Events =
	2
	3	The event system is based on the extremely flexible DOM event system.
	4
	5	When an event is fired at a target element, it '''bubbles''' up from the root to the target and then '''captures''' back down to root. Event listeners can be attached in either capture or bubble phase.
	6
	7	Binding done in RML will always attach to the '''bubble''' phase.
	8
	9	== RML binding ==
	10
	11	Event listeners can be bound to an element declared in RML by specifying an attribute with the name of the event to bind to prefixed with 'on'. For example, to bind a listener to the ''click'' event, you would declare something like the following:
	12
	13	{{{
	14	<button onclick="load game">Start Game</button>
	15	}}}
	16
	17	Note that this is the only time you prefix the event name with 'on'; all other times an event is referenced, it is done so simply with its name.
	18
	19	== Events in Python ==
	20
	21	When using the Python plugin, event listeners bound through RML execute Python code. The value of the event attribute will be executed when the event is triggered. Multiple lines of Python code can be put on one line, separated by a semicolon.
	22
	23	{{{
	24	<div onclick="print 'hello'; print 'goodbye'">
	25	}}}
	26
	27	To bind dynamically to an event in Python, the syntax is similar to Javascript:
	28	{{{
	29	element = document.GetElementById('x')
	30	element.AddEventListener('click', 'PythonCallback', False)
	31	}}}
	32
	33	Whenever an event is dispatched a there are 3 variables that are globally accessible to the called function:
	34	* '''event:''' The event object.
	35	* '''self:''' The element the event is being called on.
	36	* '''document:''' The document this element resides in.
	37
	38	== Events ==
	39
	40	Below is a list of events and their associated event attributes.
	41
	42	A number of input events send through key modifiers. In this case the following parameters are set to true if the key modifier is active when the action takes place:
	43	- ''ctrl_key''
	44	- ''shift_key''
	45	- ''meta_key''
	46	- ''alt_key''
	47	- ''caps_lock_key''
	48	- ''num_lock_key''
	49	- ''scroll_lock_key''
	50
	51	=== General ===
	52
	53	'''show'''::
	54	Sent to a document when it is made visible.
	55	'''hide'''::
	56	Sent to a document when it is made invisible.
	57	'''resize'''::
	58	Sent to an element when it resizes.
	59	'''scroll'''::
	60	Sent to an element when it is scrolled.
	61	'''focus'''::
	62	Sent to an element when it becomes the main focus.
	63	'''blur'''::
	64	Sent to an element when it has focus removed.
	65
	66	=== Keyboard Events ===
	67
	68	'''keydown'''::
	69	Sent to the focus element when a key is pressed.
	70	- ''key_identifier:'' A value from the Rocket::Core::Input::KeyIdentifier enumeration (found in ''Rocket/Core/Input.h'').
	71	- Key modifiers.
	72	'''keyup'''::
	73	Sent to the focus element when a key is released.
	74	- ''key_identifier:'' A value from the Rocket::Core::Input::KeyIdentifier enumeration.
	75	- Key modifiers.
	76	'''textinput'''::
	77	Send to the focus element when a text character is entered.
	78	- ''data:'' An EMP::Core::word corresponding to the character value.
	79
	80	=== Mouse Events ===
	81
	82	All mouse events send through key modifiers.
	83
	84	'''click'''::
	85	Sent to the element under the mouse cursor when a mouse button is clicked.
	86	- ''mouse_x:'' The mouse x position within the context.
	87	- ''mouse_y:'' The mouse y position within the context.
	88	- ''button:'' The button that was clicked.
	89	'''dblclick'''::
	90	Sent to the element under the mouse cursor when a mouse button is double clicked. Note that the ''click'' event will always be sent before ''dblclick''.
	91	- ''mouse_x:'' The mouse x position within the context.
	92	- ''mouse_y:'' The mouse y position within the context.
	93	- ''button:'' The button that was clicked.
	94	'''mouseover'''::
	95	Sent to an element as the mouse cursor moves onto it.
	96	- ''mouse_x:'' The mouse x position within the context.
	97	- ''mouse_y:'' The mouse y position within the context.
	98	'''mouseout'''::
	99	Sent to an element as the mouse cursor moves off it.
	100	- ''mouse_x:'' The mouse x position within the context.
	101	- ''mouse_y:'' The mouse y position within the context.
	102	'''mousemove'''::
	103	Sent to the element under the mouse cursor when the mouse is moved.
	104	- ''mouse_x:'' The mouse x position within the context.
	105	- ''mouse_y:'' The mouse y position within the context.
	106	'''mouseup'''::
	107	Sent to the element under the mouse cursor when a mouse button is released.
	108	- ''mouse_x:'' The mouse x position within the context.
	109	- ''mouse_y:'' The mouse y position within the context.
	110	- ''button:'' The button that was released.
	111	'''mousedown'''::
	112	Sent to the element under the mouse cursor when a mouse button is pressed down.
	113	- ''mouse_x:'' The mouse x position within the context.
	114	- ''mouse_y:'' The mouse y position within the context.
	115	- ''button:'' The button that was pressed.
	116	'''mousescroll'''::
	117	Sent to the focus element when the mouse's scroll wheel is scrolled.
	118	- ''wheel_delta:'' An integer value representing how far the wheel has been scrolled.
	119
	120	=== Dragging ===
	121
	122	All mouse drag events send through key modifiers.
	123
	124	'''dragstart'''::
	125	Sent to an element when it is first dragged, before the first ''drag'' event.
	126	- ''mouse_x:'' The mouse x position within the context.
	127	- ''mouse_y:'' The mouse y position within the context.
	128	- ''drag_element:'' The element that is being dragged.
	129	'''dragend'''::
	130	Sent to the dragged element when the mouse button is released.
	131	- ''mouse_x:'' The mouse x position within the context.
	132	- ''mouse_y:'' The mouse y position within the context.
	133	- ''drag_element:'' The element that is being dragged.
	134	'''drag'''::
	135	Sent to the dragged element when the mouse is moved.
	136	- ''mouse_x:'' The mouse x position within the context.
	137	- ''mouse_y:'' The mouse y position within the context.
	138	- ''drag_element:'' The element that is being dragged.
	139
	140	The following events are only sent if the dragged element has a ''drag'' property of ''drag-drop''. They are sent to elements other than the dragged element, usually as the mouse moves across them.
	141
	142	'''dragover'''::
	143	Sent during a drag operation to an element when the mouse cursor is moved onto the element (similarly to the ''mouseover'' event).
	144	- ''mouse_x:'' The mouse x position within the context.
	145	- ''mouse_y:'' The mouse y position within the context.
	146	- ''drag_element:'' The element that is being dragged.
	147	'''dragout'''::
	148	Sent during a drag operation to an element when the mouse cursor is moved off the element (similarly to the ''mouseout'' event).
	149	- ''mouse_x:'' The mouse x position within the context.
	150	- ''mouse_y:'' The mouse y position within the context.
	151	- ''drag_element:'' The element that is being dragged.
	152	'''dragmove'''::
	153	Sent during a drag operation to the top-most element being hovered over (excluding the dragged element) when the mouse is moved.
	154	- ''mouse_x:'' The mouse x position within the context.
	155	- ''mouse_y:'' The mouse y position within the context.
	156	- ''drag_element:'' The element that is being dragged.
	157	'''dragdrop'''::
	158	Sent at the end of a drag operation to the element the cursor is hovering over.
	159	- ''mouse_x:'' The mouse x position within the context.
	160	- ''mouse_y:'' The mouse y position within the context.
	161	- ''drag_element:'' The element that is being dragged.
	162
	163	=== Forms ===
	164
	165	'''submit'''::
	166	Sent to the form when it is submitted.
	167	- ''parameters:'' - The event object will have an attribute for each named value in the form.
	168
	169	=== Form Controls ===
	170
	171	'''change'''::
	172	Sent to a form control when its value is changed.
	173	- ''value:'' The new value.
	174
	175	=== Documents ===
	176
	177	'''load'''::
	178	Sent to a document when it is initially loaded.
	179	'''close'''::
	180	Sent to a document when it is closed.
	181
	182	=== Handle ===
	183
	184	'''handledrag'''::
	185	Sent to the handle when it is moved.
	186	- ''handle_x:'' Handle x position.
	187	- ''handle_y:'' Handle y position.
	188
	189	=== DataGrid ===
	190
	191	'''columnadd'''::
	192	Sent to the data grid when a column is added.
	193	- ''index:'' Index of the column that was added.
	194	'''rowupdate'''::
	195	Sent to the data grid when any rows in the table are loaded.
	196
	197	=== TabSet ===
	198
	199	'''tabchange'''::
	200	Sent to the tab set when the active tab is changed.
	201	- ''tab_index:'' The new tab index.