isa/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

grabHelper: Rewrite documentation for GrabHelper.grab()

Browse Source 
The previous docs were badly maintained. This does not mention
grabFocus grabs, as they'll be removed shortly.

https://bugzilla.gnome.org/show_bug.cgi?id=700735
This commit is contained in:
Jasper St. Pierre 2013-05-23 14:52:43 -04:00
parent 2f165aade8
commit 3790e924e9
1 changed files with 31 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
js/ui/grabHelper.js
View File

@ -118,34 +118,34 @@ const GrabHelper = new Lang.Class({
// grab: // grab:
// @params: A bunch of parameters, see below // @params: A bunch of parameters, see below
// //
// Grabs the mouse and keyboard, according to the GrabHelper's // The general effect of a "grab" is to ensure that the passed in actor
// parameters. If @newFocus is not %null, then the keyboard focus // and all actors inside the grab get exclusive control of the mouse and
// is moved to the first #StWidget:can-focus widget inside it. // keyboard, with the grab automatically being dropped if the user tries
// to dismiss it. The actor is passed in through @params.actor.
// //
// The grab will automatically be dropped if: // grab() can be called multiple times, with the scope of the grab being
// - The user clicks outside the grabbed actors // changed to a different actor every time. A nested grab does not have
// - The user types Escape // to have its grabbed actor inside the parent grab actors.
// - The keyboard focus is moved outside the grabbed actors
// - A window is focused
// //
// If @params.actor is not null, then it will be focused as the // Grabs can be automatically dropped if the user tries to dismiss it
// new actor. If you attempt to grab an already focused actor, the // in one of two ways: the user clicking outside the currently grabbed
// request to be focused will be ignored. The actor will not be // actor, or the user typing the Escape key.
// added to the grab stack, so do not call a paired ungrab().
// //
// If @params contains { modal: true }, then grab() will push a modal // If the user clicks outside the grabbed actors, and the clicked on
// on the owner of the GrabHelper. As long as there is at least one // actor is part of a previous grab in the stack, grabs will be popped
// { modal: true } actor on the grab stack, the grab will be kept. // until that grab is active. However, the click event will not be
// When the last { modal: true } actor is ungrabbed, then the modal // replayed to the actor.
// will be dropped. A modal grab can fail if there is already a grab
// in effect from aother application; in this case the function returns
// false and nothing happens. Non-modal grabs can never fail.
// //
// If @params contains { grabFocus: true }, then if you call grab() // If the user types the Escape key, one grab from the grab stack will
// while the shell is outside the overview, it will set the stage // be popped.
// input mode to %Shell.StageInputMode.FOCUSED, and ungrab() will //
// revert it back, and re-focus the previously-focused window (if // When a grab is popped by user interacting as described above, if you
// another window hasn't been explicitly focused before then). // pass a callback as @params.onUngrab, it will be called with %true.
//
// If @params.focus is not null, we'll set the key focus directly
// to that actor instead of navigating in @params.actor. This is for
// use cases like menus, where we want to grab the menu actor, but keep
// focus on the clicked on menu item.
grab: function(params) { grab: function(params) {
params = Params.parse(params, { actor: null, params = Params.parse(params, { actor: null,
modal: false, modal: false,
@ -262,10 +262,14 @@ const GrabHelper = new Lang.Class({
// ungrab: // ungrab:
// @params: The parameters for the grab; see below. // @params: The parameters for the grab; see below.
// //
// Pops an actor from the grab stack, potentially dropping the grab. // Pops @params.actor from the grab stack, potentially dropping
// the grab. If the actor is not on the grab stack, this call is
// ignored with no ill effects.
// //
// If the actor that was popped from the grab stack was not the actor // If the actor is not at the top of the grab stack, grabs are
// That was passed in, this call is ignored. // popped until the grabbed actor is at the top of the grab stack.
// The onUngrab callback for every grab is called for every popped
// grab with the parameter %false.
ungrab: function(params) { ungrab: function(params) {
params = Params.parse(params, { actor: this.currentGrab.actor, params = Params.parse(params, { actor: this.currentGrab.actor,
isUser: false }); isUser: false });