X & Y coordinates are in pixels, some are relative to the view, others are relative to the 4coder window. Basically the rule is that Full_Cursor is always relative to the view, but everything else is relative to the window for instance the mouse is relative to the window, and to go from mouse -> buffer X & Y you should get the view's position on the screen, find out how much it scrolled, and do the arithmetic on the mouse. I think there is a helper for this but I can't remember its name off the top of my head (global_point_to_view_point or something like that).
Permissions are meant to make it easy for the author to write commands that behave as expected for writable buffers vs read only buffers. Some commands logically work without write access to the buffer, for instance moving the cursor or copying to the clipboard. Other commands logically need write access such as write_character or paste. The goal of the API is to make it easy to get it right without having to ask for the buffer multiple times. Consider these four cases:
- writable buffer & command only needs read access
- writable buffer & command needs write access
- read only buffer & command only needs read access
- read only buffer & command needs write access
There is only one case of those four where you want the command to fail, the last case. Now the proper way to set up this API is probably to have the author of the command use constants that indicate whether the command is a logical 'read only' command or a 'needs write access' command, and then return the buffer if it is appropriate. What I have instead is a near approximation of this API where you specify that you want 'AccessOpen' when you are writing a command that needs write access and you specify 'AccessProtected' when you are writing a command that can get by with read only access.
So AccessProtected will always* return the buffer or view, even if it is writable, whereas AccessOpen will not return a read only buffer. In terms of 'narrowness' the confusion might be that 'protected' sounds narrow, but write only access is the more narrow case.
The buffer or view you get back is not at all altered by the access level you request. The only thing that changes when you change your access level is whether or not the buffer or view is returned to you at all. Once you have the buffer or view, all the API calls work on it no matter what it's read/write flags say. So you can deliberately get a read only buffer and write to it if that's what you want to do, the API is just meant to make it easy to do the thing you *probably* wanted to do.
*There is actually another rule when it comes to views. Usually views just pass along their buffer's access state. The purpose of this is because you can do a lot with just a view and again the goal is to minimize how much the author has to think about this, so instead of forcing them to get the buffer and see the result, the view just follows the rule that its buffer follows. However, views can also get into another state, where they are showing a GUI instead of the file they are associated with. In a case like this you usually don't want things like standard navigation commands to effect the buffer that you can't see. So when the view is in this state AccessProtected will not return the view. If you want to always get the view back, even when it is hiding its buffer, then you should use AccessAll. AccessAll also works when you pass it to a buffer, and I often just pass AccessAll to everything until I know for sure what the logical command type is. Finally there is another constant called AccessHidden, which I believe ONLY returns views that are hiding their file and showing a GUI, but that was just a bad API and since GUI's are changing soon anyway I recommend never using it.