Widgets and Focus

The concept of "focus" isn't a new concept in GUI systems these days, but it is most definitely a concept that is required. Focus is the redirection of input to a specific target in a GUI. In other words, if your widget grabs cursor focus then your widget gets to receive cursor events before any other widget, allowing you to perform functions that are normally not available (such as tracking cursor movement regardless of where it goes). OpenGUI provides focusing mechanisms for all input types, but due to the specifics of each input type the functionality of focusing has varying effects.

Cursor Focus (mouse input)

When no widget has cursor focus, the cursor input events are sent to all root level GUI widgets, and it is up to their discretion to pass the event on to any children they may have. This usually means that the child will not receive any cursor events until the cursor is already within the parent widget, as the default implementation for cursor events in OpenGUI::ContainerControl is to cull any events that occur while the cursor is outside of its bounds. Sometimes this is not the desired effect, so in that case a child widget can elect to grab cursor focus. Grabbing cursor focus redirects all cursor events directly to the child widget, and the rest of the GUI no longer receives any cursor events until the focus is released. This does not mean you get a "first peek with the option to defer to original processing". Once you have focus, you get it all, and everyone else gets absolutely nothing until you give up the focus. It is important to note that when you have focus, you are receiving the cursor events directly from the Screen, so the cursor position information is provided in the full Screen coordinate space. Normally the cursor input events have the cursor position information offset according to the widget's container for convenience, but again, this is not the case when you have focus.

There is no OpenGUI generated event that can occur that will force the loss of cursor focus. Once you have it, you've pretty much got it until you release it. Destruction of the widget with focus will automatically free focus, so don't worry about that. If the cursor is disabled on the screen, you may want to free your focus, but you are not obligated or forced to do so. There is, however, one condition that will cause the loss of cursor focus, and that is when another widget grabs it from you. Only one widget can ever have a particular focus at any given point in time. So when someone else asks for it when you have it, the only option is to give it to them. In practice, most cursor focuses are caused as the result of previous cursor activity, so the likelihood that you'll ever be interrupted from focusing the cursor is fairly low. However the possibility remains that some evil widget might steal it from you, so you should write your widgets with that possibility in mind.

Key Focus (keyboard input)

Key focus works much like cursor focus, with a few exceptions. The most glaring exception is that key events are not automatically sent to the root level widgets. They are only sent to widgets that specifically ask for it. The best way to receive key events is to simply grab the key focus for the duration that you need it, and release it when you're done with it. As with all focusing, only one widget can ever have any one particular focus at any point in time. Since keyboard focuses are often the result of cursor events, don't be too surprised to have your keyboard focus yanked away.