89
edits
NPAPI:Pepper: Difference between revisions
→Events
(→Events) |
(→Events) |
||
| Line 178: | Line 178: | ||
Plugins should receive all their events from NPP_HandleEvent. We believe that standardizing the event types and payloads based on, for example, DOM events, would be sufficient to provide browser and OS independent events. If not, the goal can be accomplished by possibly extending the set of event types or data on the event structures to convey more information. | Plugins should receive all their events from NPP_HandleEvent. We believe that standardizing the event types and payloads based on, for example, DOM events, would be sufficient to provide browser and OS independent events. If not, the goal can be accomplished by possibly extending the set of event types or data on the event structures to convey more information. | ||
=== | === Background === | ||
Background | Background | ||
We will use specifically sized types (int32_t, int16_t, int8_t, etc.) to avoid sizeof(int) and sizeof(wchar) differences between compilers and machine architectures, and have very strict padding and alignment specifications. | |||
This specification is version 1.0 of events in Pepper. If future events are added, or additional fields are added to existing events, we'll need a way for the | This specification is version 1.0 of events in Pepper. If future events are added, or additional fields are added to existing events, we'll need a way for the client applications to query (or negotiate) what version of events are supported by the browser. If significant changes are made to the event model, we may need to add additional trusted code to maintain backwards compatibility with existing plugin applications. This applies not only to new fields or changes to the ranges of existing fields, but is also especially important for changes or differences in behaviours across multiple operating systems (for example, are mouse movements reported outside the embedded area while a button is held down and the initial mouse down event occurred within the embedded area) Subsequent versions of Pepper events may need to support gesture & touch based events, such as finger pinching and stretching to support zoom in / zoom out for maps & photo editors. | ||
The | The plugin can use NPN_GetValue() & NPN_SetValue() to query and set future event models. Currently, only version 1.0 model is supported, and it should be safe to assume that version 1.0 model will always be available, and will be the default at startup. | ||
Additional Items | ==== Additional Items ==== | ||
There is no timer event, see NPN_ScheduleTimer() and NPN_UnscheduleTimer() for timer support. There is no quit event during application shutdown, see JavaScript's "onunload" There is no resize event; see NPN_SetWindow(), which will be correctly serialized with respect to event order. | There is no timer event, see NPN_ScheduleTimer() and NPN_UnscheduleTimer() for timer support. There is no quit event during application shutdown, see JavaScript's "onunload" There is no resize event; see NPN_SetWindow(), which will be correctly serialized with respect to event order. | ||
| Line 195: | Line 194: | ||
Currently, we are proposing a platform neutral event for focus gained/lost, and a similar event for minimize/background tab. There is also a proposal for NPAPI to support three new NPN functions: NPN_UnfocusInstance(), NPN_LostFocus(), and NPN_GotFocus(). The NPAPI proposal uses NPN functions in leu of events for a few reasons, two of which are: 1) they didn't want to define what the focus event should be for each OS platform, 2) allow the application to explicitly give up focus. Since PEPPER events are platform neutral, the 1st reason doesn't really apply here. The 2nd reason might be good enough to consider using AKH instead of focus events. The downside is that as more events become NPN_* functions, the event model starts to become an inconsistent mix of traditional events and NPN_* functions. https://wiki.mozilla.org/Plugins:AdvancedKeyHandling | Currently, we are proposing a platform neutral event for focus gained/lost, and a similar event for minimize/background tab. There is also a proposal for NPAPI to support three new NPN functions: NPN_UnfocusInstance(), NPN_LostFocus(), and NPN_GotFocus(). The NPAPI proposal uses NPN functions in leu of events for a few reasons, two of which are: 1) they didn't want to define what the focus event should be for each OS platform, 2) allow the application to explicitly give up focus. Since PEPPER events are platform neutral, the 1st reason doesn't really apply here. The 2nd reason might be good enough to consider using AKH instead of focus events. The downside is that as more events become NPN_* functions, the event model starts to become an inconsistent mix of traditional events and NPN_* functions. https://wiki.mozilla.org/Plugins:AdvancedKeyHandling | ||
Pepper NPAPI Event Structures | ==== Pepper NPAPI Event Structures ==== | ||
It is important that all compilers, on all supported platforms, both trusted and untrusted, preserve structure order, field size, and alignment padding, as these structures might be used as a bit copyable wire format between different processes. These seperate processses could be compiled using different compilers and/or compilier options, while sharing these structures via shared memory. For the definitions below, the byte offset for each field is in square brackets. Unused portions of the event structure should be treated as undefined data. | It is important that all compilers, on all supported platforms, both trusted and untrusted, preserve structure order, field size, and alignment padding, as these structures might be used as a bit copyable wire format between different processes. These seperate processses could be compiled using different compilers and/or compilier options, while sharing these structures via shared memory. For the definitions below, the byte offset for each field is in square brackets. Unused portions of the event structure should be treated as undefined data. | ||
| Line 206: | Line 205: | ||
NPMouseButton_Middle = 1, | NPMouseButton_Middle = 1, | ||
NPMouseButton_Right = 2, | NPMouseButton_Right = 2, | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future mouse button enums go here... | // Additional future mouse button enums go here... | ||
}; | }; | ||
| Line 228: | Line 227: | ||
NPEventType_Focus = 11, // NPFocusEvent struct | NPEventType_Focus = 11, // NPFocusEvent struct | ||
NPEventType_Device = 12, // NPDeviceEvent struct | NPEventType_Device = 12, // NPDeviceEvent struct | ||
// End of | // End of Pepper specific event specification version 1.0 | ||
// Additional future | // Additional future Pepper events go here... | ||
}; | }; | ||
| Line 243: | Line 242: | ||
NPEventModifier_MiddleButtonDown = 1 << 7; | NPEventModifier_MiddleButtonDown = 1 << 7; | ||
NPEventModifier_RightButtonDown = 1 << 8; | NPEventModifier_RightButtonDown = 1 << 8; | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future event modifiers go here... | // Additional future event modifiers go here... | ||
}; | }; | ||
| Line 257: | Line 256: | ||
uint16_t text[4]; // [4] : 32bit wchar | uint16_t text[4]; // [4] : 32bit wchar | ||
uint16_t unmodifiedText[4]; // [8] : 32bit wchar | uint16_t unmodifiedText[4]; // [8] : 32bit wchar | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future key event fields go here... | // Additional future key event fields go here... | ||
}; | }; | ||
| Line 268: | Line 267: | ||
int32_t y; // [12]: Relative to upper left corner of embedded area (+y down) | int32_t y; // [12]: Relative to upper left corner of embedded area (+y down) | ||
int32_t clickCount; // [16]: Number of button clicks | int32_t clickCount; // [16]: Number of button clicks | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future mouse event fields go here... | // Additional future mouse event fields go here... | ||
}; | }; | ||
| Line 282: | Line 281: | ||
// Wheel ticks can be fractional values on certain devices. | // Wheel ticks can be fractional values on certain devices. | ||
uint32_t scrollByPage; // [20]: 0 - scroll by line, 1 - scroll by page | uint32_t scrollByPage; // [20]: 0 - scroll by line, 1 - scroll by page | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future mouse wheel event fields go here... | // Additional future mouse wheel event fields go here... | ||
}; | }; | ||
| Line 303: | Line 302: | ||
// 0 = transitioning out of minimized state | // 0 = transitioning out of minimized state | ||
// 1 = transitioning to a minimized state | // 1 = transitioning to a minimized state | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future minimize event fields go here... | // Additional future minimize event fields go here... | ||
}; | }; | ||
| Line 309: | Line 308: | ||
struct NPFocusEvent { | struct NPFocusEvent { | ||
// Structure layout must match between trusted & untrusted code. | // Structure layout must match between trusted & untrusted code. | ||
// The embedded | // The embedded Pepper area is gaining or losing keyboard focus. | ||
int32_t value; // [0] : New value | int32_t value; // [0] : New value | ||
// 0 = losing focus | // 0 = losing focus | ||
// 1 = gaining focus | // 1 = gaining focus | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future focus event fields go here... | // Additional future focus event fields go here... | ||
}; | }; | ||
| Line 332: | Line 331: | ||
NPFocusEvent focus; | NPFocusEvent focus; | ||
NPDeviceEvent device; | NPDeviceEvent device; | ||
// End of | // End of Pepper event specification version 1.0 | ||
// Additional future event type structures go here... | // Additional future event type structures go here... | ||
}; | }; | ||