gnustep/libs-back
0
0
Fork 0
mirror of https://github.com/gnustep/libs-back.git synced 2025-02-23 20:01:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

New docs

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/back/trunk@15686 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Adam Fedor 2003-01-24 04:37:40 +00:00
parent ed1f725c5c
commit 664673ec0e
6 changed files with 506 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
2003-01-23 Adam Fedor <fedor@gnu.org>
* Documentation/Back: Some documentation.
2003-01-20 Adam Fedor <fedor@gnu.org>
* Source/gsc/GSStreamContext.m (-GSSetCTM:): Implement.

24
Documentation/Back/Back.gsdoc Normal file
View file

@ -0,0 +1,24 @@
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.7//EN" "http://www.gnustep.org/gsdoc-0_7_0.xml">
<gsdoc base="Back">
<head>
<title>Back</title>
<author name="Adam Fedor">
<email address="fedor@gnu.org"/>
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
</author>
<version>$Revision$</version>
<date>$Date$</date>
</head>
<body>
<chapter>
<heading>Back</heading>
<p>
Documentation for understanding and writting GUI backends.
</p>
<list>
<item><uref url="WindowFocus.html">Window Focus</uref></item>
</list>
</chapter>
</body>
</gsdoc>

31
Documentation/Back/Back.html Normal file
View file

@ -0,0 +1,31 @@
<html>
<head>
<title>Back</title>
</head>
<body>
<br />
<h1><a name="title$Back">Back</a></h1>
<h3>Authors</h3>
<dl>
<dt><a href="http://www.gnustep.org/developers/whoiswho.html">Adam Fedor</a>(<a href="mailto:fedor@gnu.org"><code></code></a>)</dt>
<dd>
</dd>
</dl>
<p><b>Version:</b> $Revision$</p>
<p><b>Date:</b> $Date$</p>
<h1><a name="001000000000">Back</a></h1>
<p>
Documentation for understanding and writting GUI backends.
</p>
<ul>
<li>
<a href="WindowFocus.html">Window Focus</a>
</li>
</ul>
<br />
</body>
</html>

49
Documentation/Back/GNUmakefile Normal file
View file

@ -0,0 +1,49 @@
#
# Gui gsdoc makefile for the GNUstep Back Library
# Copyright (C) 2000 Free Software Foundation, Inc.
#
# Written by: Adam Fedor <fedor@gnu.org>
#
# 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

179
Documentation/Back/WindowFocus.gsdoc Normal file
View file

@ -0,0 +1,179 @@
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.7//EN" "/usr/GNUstep/System/Libraries/Resources/DTDs/gsdoc-0_7_0.dtd" >
<gsdoc base="WindowFocus">
<head>
<title>Window Focus Procedures</title>
<author name="Adam Fedor">
<email address="fedor@gnu.org"/>
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
</author>
<version>$Revision$</version>
<date>$Date$</date>
</head>
<body>
<chapter>
<heading>Window Focus</heading>
<p>
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.
</p>
<section>
<heading>Application Focus</heading>
<p>
The application can get focus in several ways.
</p>
<list>
<item>Launch from the command line or another app</item>
<item>Another app looses focus (e.g. by terminating)</item>
<item>Users switches screens to the one the app is displayed on</item>
<item>Double-click on the application icon</item>
</list>
<p>
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.
</p>
<p>
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.
</p>
<p>
The last case is handled mostly in the GUI front-end.
</p>
</section>
<section>
<heading>KeyboardFocus</heading>
<p>
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.
</p>
<p>
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.
</p>
<deflist>
<term>WindowMaker</term>
<desc>
<p>
WindowMaker controls the application icon so it does not
receive keyboard events
</p>
</desc>
</deflist>
</section>
<section>
<heading>Requesting Keyboard Focus</heading>
<p>
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.
</p>
<p>
If the window is ordered front and the window is the key window,
it will send a setinputfocus: message.
</p>
<p>
If during _lossOfKeyOrMainWindow, only the main menu is able to
become key, it will sent a setinputfoucs: message.
</p>
</section>
<section>
<heading>Window Focus In/Out</heading>
<p>
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:
</p>
<list>
<item>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. </item>
<item>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. </item>
<item>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. </item>
<item>If this window is the main menu, it looks for another
window to become the key window, if possible, through the
_lossOfKeyOrMainWindow mechanism</item>
</list>
<p>
The front-end does nothing for FocusOut messages.
</p>
</section>
<section>
<heading>X-Windows messages</heading>
<p>
This section describes messages that X-Windows servers and WM
generally send to the application.
</p>
<deflist>
<term>Take Focus</term>
<desc>
<p>
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.
</p>
</desc>
<term>Focus In</term>
<desc>
<p>
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).
</p>
</desc>
<term>Focus Out</term>
<desc>
<p>
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.
</p>
</desc>
</deflist>
</section>
</chapter>
</body>
</gsdoc>

219
Documentation/Back/WindowFocus.html Normal file
View file

@ -0,0 +1,219 @@
<html>
<head>
<title>Window Focus Procedures</title>
</head>
<body>
<br />
<h1><a name="title$WindowFocus">Window Focus Procedures</a></h1>
<h3>Authors</h3>
<dl>
<dt><a href="http://www.gnustep.org/developers/whoiswho.html">Adam Fedor</a>(<a href="mailto:fedor@gnu.org"><code></code></a>)</dt>
<dd>
</dd>
</dl>
<p><b>Version:</b> $Revision$</p>
<p><b>Date:</b> $Date$</p>
<h1><a name="001000000000">Window Focus</a></h1>
<p>
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.
</p>
<h2><a name="001001000000">Application Focus</a></h2>
<p>
The application can get focus in several ways.
</p>
<ul>
<li>
Launch from the command line or another app
</li>
<li>
Another app looses focus (e.g. by terminating)
</li>
<li>
Users switches screens to the one the app is displayed on
</li>
<li>
Double-click on the application icon
</li>
</ul>
<p>
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.
</p>
<p>
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.
</p>
<p>
The last case is handled mostly in the GUI front-end.
</p>
<h2><a name="001002000000">KeyboardFocus</a></h2>
<p>
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.
</p>
<p>
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.
</p>
<dl>
<dt>WindowMaker</dt>
<dd>
<p>
WindowMaker controls the application icon so it does not
receive keyboard events
</p>
</dd>
</dl>
<h2><a name="001003000000">Requesting Keyboard Focus</a></h2>
<p>
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.
</p>
<p>
If the window is ordered front and the window is the key window,
it will send a setinputfocus: message.
</p>
<p>
If during _lossOfKeyOrMainWindow, only the main menu is able to
become key, it will sent a setinputfoucs: message.
</p>
<h2><a name="001004000000">Window Focus In/Out</a></h2>
<p>
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:
</p>
<ul>
<li>
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.
</li>
<li>
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.
</li>
<li>
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.
</li>
<li>
If this window is the main menu, it looks for another
window to become the key window, if possible, through the
_lossOfKeyOrMainWindow mechanism
</li>
</ul>
<p>
The front-end does nothing for FocusOut messages.
</p>
<h2><a name="001005000000">X-Windows messages</a></h2>
<p>
This section describes messages that X-Windows servers and WM
generally send to the application.
</p>
<dl>
<dt>Take Focus</dt>
<dd>
<p>
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.
</p>
</dd>
<dt>Focus In</dt>
<dd>
<p>
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).
</p>
</dd>
<dt>Focus Out</dt>
<dd>
<p>
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.
</p>
</dd>
</dl>
<br />
</body>
</html>