diff --git a/ChangeLog b/ChangeLog index 9989e73..95934f3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2003-01-23 Adam Fedor + + * Documentation/Back: Some documentation. + 2003-01-20 Adam Fedor * Source/gsc/GSStreamContext.m (-GSSetCTM:): Implement. diff --git a/Documentation/Back/Back.gsdoc b/Documentation/Back/Back.gsdoc new file mode 100644 index 0000000..c4acf7c --- /dev/null +++ b/Documentation/Back/Back.gsdoc @@ -0,0 +1,24 @@ + + + + + Back + + + + + $Revision$ + $Date$ + + + + Back +

+ Documentation for understanding and writting GUI backends. +

+ + Window Focus + + + + diff --git a/Documentation/Back/Back.html b/Documentation/Back/Back.html new file mode 100644 index 0000000..56d3e03 --- /dev/null +++ b/Documentation/Back/Back.html @@ -0,0 +1,31 @@ + + + + Back + + +
+

Back

+

Authors

+
+
Adam Fedor()
+
+
+
+

Version: $Revision$

+

Date: $Date$

+ + +

Back

+

+ + Documentation for understanding and writting GUI backends. +

+ +
+ + diff --git a/Documentation/Back/GNUmakefile b/Documentation/Back/GNUmakefile new file mode 100644 index 0000000..3b1f323 --- /dev/null +++ b/Documentation/Back/GNUmakefile @@ -0,0 +1,49 @@ +# +# Gui gsdoc makefile for the GNUstep Back Library +# Copyright (C) 2000 Free Software Foundation, Inc. +# +# Written by: Adam Fedor +# +# This file is part of the GNUstep Back Library. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Library General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Library General Public License for more details. +# +# You should have received a copy of the GNU Library General Public +# License along with this library; if not, write to the Free +# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +# Install into the system root by default +GNUSTEP_INSTALLATION_DIR = $(GNUSTEP_SYSTEM_ROOT) + +GNUSTEP_MAKEFILES = $(GNUSTEP_SYSTEM_ROOT)/Makefiles + +include $(GNUSTEP_MAKEFILES)/common.make + +# The documents to be generated +DOCUMENT_NAME = Back + +Back_AGSDOC_FILES = \ + Back.gsdoc \ + WindowFocus.gsdoc + +Back_AGSDOC_FLAGS = \ + -DocumentationDirectory . \ + -Up Back + +Back_DOC_INSTALL_DIR = Developer/Back/Reference + +-include GNUmakefile.preamble + +-include GNUmakefile.local + +include $(GNUSTEP_MAKEFILES)/documentation.make + +-include GNUmakefile.postamble diff --git a/Documentation/Back/WindowFocus.gsdoc b/Documentation/Back/WindowFocus.gsdoc new file mode 100644 index 0000000..1553c2e --- /dev/null +++ b/Documentation/Back/WindowFocus.gsdoc @@ -0,0 +1,179 @@ + + + + + Window Focus Procedures + + + + + $Revision$ + $Date$ + + + + Window Focus +

+ This document describes how various system and user actions + affect window focus of GNUstep applications. This document describes + focus changes that occur outside of application control, since + application focus changes are well described in the class + documentation. +

+ +
+ Application Focus +

+ The application can get focus in several ways. +

+ + Launch from the command line or another app + Another app looses focus (e.g. by terminating) + Users switches screens to the one the app is displayed on + Double-click on the application icon + +

+ The first case does not directly affect window focus (because there + are no windows at startup). However, as the application begins to + create an order front windows (including the main menu) there will + likely be a cascade of focus events generated by the window manager. +

+

+ In the second and third case, the window manager will likely try + to give focus to the window that previously had it or perhaps to some + random window based on some internal window manager + code. GNUstep may ignore this and try to give focus to another + window. +

+

+ The last case is handled mostly in the GUI front-end. +

+
+ +
+ KeyboardFocus +

+ The Key window is the window that has keyboard focus and has + keyboard events sent to it. When an application is launched, in + many cases, only the application icon and main menu may be + displayed. In the OpenStep interface, neither of these is really + supposed to be a key window, and in fact, many window managers + control the application icon so this cannot be made key + anyway. In X-Windows, however, there is no other way for an + application to receive keyboard events unless a visible window + has been made key. This leaves the main menu. +

+

+ When an application receives focus, or if all the windows in an + application are closed (see [NSWindow-_lossOfKeyOrMainWindow]), + then the main menu should get keyboard focus. This is handled in + the gui frontend, so there should be nothing special done in the + backend to support this. +

+ + WindowMaker + +

+ WindowMaker controls the application icon so it does not + receive keyboard events +

+ + +
+ +
+ Requesting Keyboard Focus +

+ A window may request to get keyboard focus in serveral + instances. If the window asks or is asked to become key, through + the [NSWindow-becomeKeyWindow] method, it will send a + setinputfocus: message to the server. +

+

+ If the window is ordered front and the window is the key window, + it will send a setinputfocus: message. +

+

+ If during _lossOfKeyOrMainWindow, only the main menu is able to + become key, it will sent a setinputfoucs: message. +

+
+ +
+ Window Focus In/Out +

+ The GUI front-end receives two types of focus events from the + back-end (through an NSEvent object). Both of these are subsets + of the NSAppKitDefined event: GSAppKitWindowFocusIn and + GSAppKitWindowFocusOut. Each contains a pointer to the window + that should be focused. A focus in event can be received for + several reasons: +

+ + The window manager deminiaturized the window. The WM + should really tell the application to do this itself, but many + WM don't. In this case the window just posts a notification + that it happened. + The application is in the process of hidding. As each + window is ordered out, the WM may send a focus message + (spuriously) to the next window in line. In this case the + message is just ignored. + This is a real focus in message. The window checks if it + can become key or main and activates the application if it is + not active. + If this window is the main menu, it looks for another + window to become the key window, if possible, through the + _lossOfKeyOrMainWindow mechanism + +

+ The front-end does nothing for FocusOut messages. +

+
+ +
+ X-Windows messages +

+ This section describes messages that X-Windows servers and WM + generally send to the application. +

+ + Take Focus + +

+ A message from the WM telling a window it should take + keyboard focus. The back-end should only send a FocusIn event + to the front end if the window asked to be key (and isn't + already) or through a user action, such as a click on the + title bar. The back-end may also send an event if the window + has just been mapped, although this is not typically + necessary, unless it's due to a screen change. +

+ + Focus In + +

+ A message from the server telling the application that + keyboard focus has been set for a window. The back-end + should not send an event to the front-end in this + case. However, the back-end should use this information to + determine when to send a message in other cases (e.g. from a + Take Focus message). +

+ + Focus Out + +

+ A message from the server telling the application that focus + has left a window. If the focus has gone to a window that is + not part of the application, the back-end should tell the + NSApp to deactivate. Otherwise it should do nothing. +

+ + +
+ + + + + + diff --git a/Documentation/Back/WindowFocus.html b/Documentation/Back/WindowFocus.html new file mode 100644 index 0000000..3a20678 --- /dev/null +++ b/Documentation/Back/WindowFocus.html @@ -0,0 +1,219 @@ + + + + Window Focus Procedures + + +
+

Window Focus Procedures

+

Authors

+
+
Adam Fedor()
+
+
+
+

Version: $Revision$

+

Date: $Date$

+ + +

Window Focus

+

+ + This document describes how various system and user actions + affect window focus of GNUstep applications. This document describes + focus changes that occur outside of application control, since + application focus changes are well described in the class + documentation. +

+ +

Application Focus

+

+ + The application can get focus in several ways. +

+
    +
  • + Launch from the command line or another app +
    • +
  • + Another app looses focus (e.g. by terminating) +
    • +
  • + Users switches screens to the one the app is displayed on +
    • +
  • + Double-click on the application icon +
    • +
+

+ + The first case does not directly affect window focus (because there + are no windows at startup). However, as the application begins to + create an order front windows (including the main menu) there will + likely be a cascade of focus events generated by the window manager. +

+

+ + In the second and third case, the window manager will likely try + to give focus to the window that previously had it or perhaps to some + random window based on some internal window manager + code. GNUstep may ignore this and try to give focus to another + window. +

+

+ + The last case is handled mostly in the GUI front-end. +

+ +

KeyboardFocus

+

+ + The Key window is the window that has keyboard focus and has + keyboard events sent to it. When an application is launched, in + many cases, only the application icon and main menu may be + displayed. In the OpenStep interface, neither of these is really + supposed to be a key window, and in fact, many window managers + control the application icon so this cannot be made key + anyway. In X-Windows, however, there is no other way for an + application to receive keyboard events unless a visible window + has been made key. This leaves the main menu. +

+

+ + When an application receives focus, or if all the windows in an + application are closed (see [NSWindow-_lossOfKeyOrMainWindow]), + then the main menu should get keyboard focus. This is handled in + the gui frontend, so there should be nothing special done in the + backend to support this. +

+
+
WindowMaker
+
+ + +

+ + WindowMaker controls the application icon so it does not + receive keyboard events +

+ + +
+
+ +

Requesting Keyboard Focus

+

+ + A window may request to get keyboard focus in serveral + instances. If the window asks or is asked to become key, through + the [NSWindow-becomeKeyWindow] method, it will send a + setinputfocus: message to the server. +

+

+ + If the window is ordered front and the window is the key window, + it will send a setinputfocus: message. +

+

+ + If during _lossOfKeyOrMainWindow, only the main menu is able to + become key, it will sent a setinputfoucs: message. +

+ +

Window Focus In/Out

+

+ + The GUI front-end receives two types of focus events from the + back-end (through an NSEvent object). Both of these are subsets + of the NSAppKitDefined event: GSAppKitWindowFocusIn and + GSAppKitWindowFocusOut. Each contains a pointer to the window + that should be focused. A focus in event can be received for + several reasons: +

+
    +
  • + The window manager deminiaturized the window. The WM + should really tell the application to do this itself, but many + WM don't. In this case the window just posts a notification + that it happened. +
    • +
  • + The application is in the process of hidding. As each + window is ordered out, the WM may send a focus message + (spuriously) to the next window in line. In this case the + message is just ignored. +
    • +
  • + This is a real focus in message. The window checks if it + can become key or main and activates the application if it is + not active. +
    • +
  • + If this window is the main menu, it looks for another + window to become the key window, if possible, through the + _lossOfKeyOrMainWindow mechanism +
    • +
+

+ + The front-end does nothing for FocusOut messages. +

+ +

X-Windows messages

+

+ + This section describes messages that X-Windows servers and WM + generally send to the application. +

+
+
Take Focus
+
+ + +

+ + A message from the WM telling a window it should take + keyboard focus. The back-end should only send a FocusIn event + to the front end if the window asked to be key (and isn't + already) or through a user action, such as a click on the + title bar. The back-end may also send an event if the window + has just been mapped, although this is not typically + necessary, unless it's due to a screen change. +

+ + +
+
Focus In
+
+ + +

+ + A message from the server telling the application that + keyboard focus has been set for a window. The back-end + should not send an event to the front-end in this + case. However, the back-end should use this information to + determine when to send a message in other cases (e.g. from a + Take Focus message). +

+ + +
+
Focus Out
+
+ + +

+ + A message from the server telling the application that focus + has left a window. If the focus has gone to a window that is + not part of the application, the back-end should tell the + NSApp to deactivate. Otherwise it should do nothing. +

+ + +
+
+
+ +