Confirmed users, Bureaucrats and Sysops emeriti
1,680
edits
NPAPI:AdvancedKeyHandling: Difference between revisions
Jump to navigation
Jump to search
no edit summary
No edit summary |
|||
| Line 25: | Line 25: | ||
* Any API should allow for focus direction to be recalled and followed - plugins should know what direction focus is coming from when being focused, and the browser should know which direction focus is going when unfocusing the plugin. | * Any API should allow for focus direction to be recalled and followed - plugins should know what direction focus is coming from when being focused, and the browser should know which direction focus is going when unfocusing the plugin. | ||
* Plugins should be able to hand events to the browser when they want to, regardless of the source. This would allow the browser to handle events the plugin does not want to handle. | * Plugins should be able to hand events to the browser when they want to, regardless of the source. This would allow the browser to handle events the plugin does not want to handle. | ||
= Current Proposal = | |||
=== Specification === | |||
'''NPAPI Advanced Key Handling (AKH) Support''' | |||
* Last modified: February 25, 2009 | |||
* Author: Josh Aas, Mozilla Corporation | |||
* Contributors: Johnny Stenback (Mozilla), Aaron Leventhal (IBM), Oliver Yeoh (Sun), Danielle Pham (Sun), Deneb Mateka (Adobe), Anders Carlsson (Apple) | |||
Under this proposal, existing behavior does not change. In order for behavior to change, the browser must return a boolean value of "true" for "NPNVSupportsAdvancedKeyHandling" *and* the plugin must return a boolean value of "true" for "NPPVSupportsAdvancedKeyHandling". There is no active negotiation of modes and supported status cannot change at any time for either the browser or the plugin. | |||
The rest of this specification describes behavior specific to AKH mode. | |||
For windowed plugins, events that the browser should attempt to handle can be forwarded to the browser via a new function. | |||
<pre> | |||
// Called by windowed plugins to pass an event on to the browser. | |||
// Instance argument indicates the instance sending the event. | |||
// Event argument is the event being forwarded. | |||
// Handled argument indicates whether or not the plugin already handled the event. | |||
// This encourages the forwarding of all events even if the plugin already handled them. | |||
// The browser is then able to take further action if that is necessary for some reason. | |||
// Return value indicates whether or not the browser handled the event. | |||
NPBool NPN_HandleEvent(NPP instance, NPEvent *event, NPBool handled); | |||
</pre> | |||
For windowless plugins, returning 0 from NPP_HandleEvent will allow the browser to handle the event. For example, returning 0 for a tab key event will allow the browser to process the tab key event, and the browser may choose to take focus from the plugin. | |||
For both windowed and windowless plugins, there will be 3 function and a set of enum values controlling focus. | |||
<pre> | |||
enum { | |||
NPFocusNext = 0, | |||
NPFocusPrevious = 1 | |||
} NPFocusDirection; | |||
// Called by the plugin when the plugin intends to give up focus. | |||
// Instance argument indicates the instance wishing to give up focus. | |||
// Direction argument indicates whether the next or the previous element should take focus. | |||
// Return value indicates whether or not the browser will take focus. | |||
NPBool NPN_GiveUpFocus(NPP instance, NPFocusDirection direction); | |||
// Called by the browser when the browser intends to take focus. | |||
// Instance argument indicates the instances losing focus. | |||
// Direction argument indicates the direction of the element receiving focus. | |||
// There is no return value, plugins will lose focus when this is called. | |||
NPBool NPP_LostFocus(NPP instance, NPFocusDirection direction); | |||
// Called by the browser when the browser intends to focus an instance. | |||
// Instance argument indicates the instance getting focus. | |||
// Direction argument indicates the direction in which focus advanced to the instance. | |||
// Return value indicates whether or not the plugin accepts focus. | |||
NPBool NPP_GotFocus(NPP instance, NPFocusDirection direction); | |||
</pre> | |||
When a plugin takes focus, it will receive an <tt>NPP_GotFocus</tt> call before receiving the event that gave it focus (such as a mouse click). | |||
If a plugin receives an event that causes it to attempt to give up focus, the plugin should simply call NPN_GiveUpFocus and not pass on the event since attempting to give up focus is essentially handling the event. | |||
Focus events will not be passed to plugins via <tt>NPP_HandleEvent</tt> when AKH is enabled. Per platform, this means: | |||
* Mac OS X (windowless): <tt>NPEventType_GetFocusEvent</tt> and <tt>NPEventType_LoseFocusEvent</tt> will not be sent. | |||
* Windows (windowless): <tt>WM_SETFOCUS</tt> and <tt>WM_KILLFOCUS</tt> will not be sent. | |||
* Windows (windowed): coming soon | |||
* GTK (non-xembed windowless): coming soon | |||
* GTK (non-xembed windowed): coming soon | |||
* GTK (xembed): coming soon | |||
=== Comments === | |||
Consider <tt>HandleEvent</tt> return value. | |||
Do we need a more advanced event propagation system for windowed plugins, such as the systems described in Sun's September 2007 proposal? | |||
We need to outline exactly how this affects existing focus events, such as XEmbed and Carbon focus events. | |||
What about [https://bugzilla.mozilla.org/show_bug.cgi?id=78414#c236 this 2008 proposal] to slightly change the current behavior and allow users to escape legacy plugins by hitting the F6 key? | |||
= Past Proposals and Commentary = | = Past Proposals and Commentary = | ||
| Line 383: | Line 462: | ||
How exactly is the browser supposed to send GetFocusFirstEvent/GetFocusLastEvent events to the plugin via existing NPP_HandleEvent. NPEvent data is different on each platform, it isn't clear how that would be conveyed when, for example, the type for NPEvent is "void*", a pointer to a native event structure. | How exactly is the browser supposed to send GetFocusFirstEvent/GetFocusLastEvent events to the plugin via existing NPP_HandleEvent. NPEvent data is different on each platform, it isn't clear how that would be conveyed when, for example, the type for NPEvent is "void*", a pointer to a native event structure. | ||