new manual modeled after one in Base but without Objective-C discussion

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@19597 72102866-910b-0410-8b05-ffd578937521

Documentation/manual/BasicClasses.texi

@@ -0,0 +1,58 @@
+@paragraphindent 0
+
+@node Basic Classes
+@chapter Basic Classes
+
+This is a simple introduction to the major classes in the GNUstep GUI library
+API.  If you know nothing about the OpenStep AppKit, it could be a good idea
+to read this before you start reading the reference documentation.
+
+I am very interested in comments regarding this text, particularly from people
+who are new to the OPENSTEP AppKit API.  Send comments and/or suggestions to
+Nicola Pero (n.pero@@mi.flashnet.it).
+
+
+@section NSView
+@cindex NSView class
+
+NSView is the class of objects representing a rectangular area (usually in a
+window) with its own coordinate system.  Views have methods to draw inside the
+view, to change the view's coordinate system, and to place the view with
+arbitrary position and size inside another view.  When you place a view inside
+another view, you are technically making the smaller view a <em>subview</em>
+of the bigger view.  The whole drawable area inside the window itself is
+represented by a view, called the <em>content view</em>.  All the visible
+views in a window are then subviews of the content view of that window (or of
+the content view's subviews etc).  This gives rise to what is called the "view
+tree" of the window.
+
+
+@section NSCell
+@cindex NSCell class
+
+NSCell is the class of objects representing a single amount of displayable
+data.  For example, a cell could represent a number, or a string, or an image.
+Cells have methods to draw the data they represent in a view, to change the
+way the data is to be drawn (eg the font for a string or the border for an
+image), and to let the user interact directly (eg editing the data) with the
+data in a view.
+
+
+@section NSControl
+@cindex NSControl class
+
+NSControl is the class of objects representing a view (i.e., a rectangular
+area in a window) used to manage one or more cells (i.e., some displayable
+data).  This class is usually designed to work with a subclass of NSCell,
+called <em>NSActionCell</em>, through a system of target/action.  Each
+actioncell has a <em>target</em> - an object - and an <em>action</em> - a
+selector - both of which can be arbitrarily set.  The control can then ask the
+cell to send its action to its target (ie, to invoke the method of the target
+object identified by the selector) as a consequence of user actions in the
+control.  The typical example is a button: a button is a control with a
+corresponding cell; when the user presses the button, the buttoncell sends its
+action to its target.  Controls are the high-level objects the you usually
+deal with when designing everyday-life user interfaces.  You do not usually
+need to bother about cells, because the controls manage the cells for you.
+
+@page

Documentation/manual/GNUmakefile

@@ -0,0 +1,17 @@
+
+include $(GNUSTEP_MAKEFILES)/common.make
+
+#GNUSTEP_MAKEINFO_FLAGS = -D NO-TEXI2HTML
+
+DOCUMENT_NAME = manual
+
+manual_TEXI_FILES =              \
+	manual.texi              \
+	Introduction.texi        \
+	BasicClasses.texi
+
+manual_DOC_INSTALL_DIR = Developer/Gui/ProgrammingManual
+
+include $(GNUSTEP_MAKEFILES)/documentation.make
+
+

Documentation/manual/Introduction.texi

@@ -0,0 +1,217 @@
+@paragraphindent 0
+
+@node Introduction
+@chapter Introduction
+
+This manual documents some configuration and installation issues
+with the GNUstep GUI Library and also differences between the GUI
+Library and libraries that implement the OpenStep AppKit specification
+and the MacOS-X AppKit implementation.
+
+@section Overview
+
+The GNUstep GUI Library is a library of objects useful for writing
+graphical applications.  For example, it includes classes for drawing
+and manipulating graphics objects on the screen: windows, menus,
+buttons, sliders, text fields, and events.  There are also many
+peripheral classes that offer operating-system-independent interfaces to
+images, cursors, colors, fonts, pasteboards, printing.  There are also
+workspace support classes such as data links, open/save panels,
+context-dependent help, spell checking.
+
+It provides functionality that aims to implement the @samp{AppKit}
+portion of the OpenStep standard.  However the implementation has
+been written to take advantage of GNUstep enhancements wherever possible.
+
+The GNUstep GUI Library is divided into a front and back-end.  The
+front-end contains the majority of implementation, but leaves out the
+low-level drawing and event code.  Different back-ends will make GNUstep
+available on various platforms.  The default GNU back-end currently runs
+on top of the X Window System and uses only Xlib calls for
+graphics. Another backend uses a Display Postscript Server for graphics.
+Much work will be saved by this clean separation between front and
+back-end, because it allows different platforms to share the large
+amount of front-end code. Documentation for how the individual backends
+work is coverered in a separate document.
+
+@section Implementation Details
+
+Following are some implementation details of the GUI library. These will
+mostly be of interest to developers of the GUI library itself.
+
+@subsection Drag and Drop
+
+The drag types info for each view is kept in a global map table (protected by
+locks) and can be accessed by the backend library using the function -
+
+@smallexample
+NSArray *GSGetDragTypes(Nsview *aView);
+@end smallexample
+
+Drag type information for each window (a union of the drag type info for all
+the views in the window) is maintained in the graphics context.
+The backend can get this information (as a counted set) using -
+
+@smallexample
+- (NSCountedSet*) _dragTypesForWindow: (int)winNum;
+@end smallexample
+
+Whenever a DnD aware view is added to, or removed from a window, the type
+information for that view is added to/removed from the type information
+for the window, altering the counted set.  If the alteration results in a
+change in the types for the window, the method making the change returns YES.
+
+@smallexample
+- (BOOL) _addDragTypes: (NSArray*)types toWindow: (int)winNum;
+- (BOOL) _removeDragTypes: (NSArray*)types fromWindow: (int)winNum;
+@end smallexample
+
+The backend library should therefore override these methods and call 'super'
+to handle the update.  If the call to the super method returns YES, the
+backend should make any changes as appropriate (in the case of the xdnd
+protocol this means altering the XdndAware property of the X window).
+
+You will notice that these methods use the integer window number rather
+than the NSWindow object - this is for the convenience of the backend
+library which should (eventually) use window numbers for everything
+
+@subsection NSWorkspace
+
+Here is (I think) the current state of the code (largely untested) -
+
+The make_services tool examines all applications (anything with a .app,
+.debug, or .profile suffix) in the system, local, and user Apps Directories.
+
+In addition to the cache of services information, it builds a cache of
+information about known applications (including information about file types
+they handle).
+
+NSWorkspace reads the cache and uses it to determine which application to use
+to open a document and which icon to use to represent that document.
+
+The NSWorkspace API has been extended to provide methods for finding/setting
+the preferred icon/application for a particular file type.  NSWorkspace will
+use the 'best' icon/application available.
+
+To determine the executable to launch, if there was an
+Info-gnustep.plist/Info.plist in the app wrapper and it had an
+NSExecutable field - use that name.  Otherwise, try to use the name of
+the app - eg. foo.app/foo The executable is launched by NSTask, which
+handles the addition of machine/os/library path components as necessary.
+
+To determine the icon for a file, use the value from the cache of icons
+for the file extension, or use an 'unknown' icon.
+
+To determine the icon for a folder, if the folder has a '.app', '.debug'
+or '.profile' extension - examine the Info.plist file for an 'NSIcon'
+value and try to use that.  If there is no value specified - try
+foo.app/foo.tiff' or 'foo.app/.dir.tiff'
+
+If the folder was not an application wrapper, just try the .dir.tiff file.
+
+If no icon was available, use a default folder icon or a special icon for the
+root directory.
+
+The information about what file types an app can handle needs to be in
+the MacOS-X format in the Info-gnustep.plist/Info.plist for the app -
+see
+@url{http://developer.apple.com/techpubs/macosxserver/System/Documentation/Developer/YellowBox/ReleaseNotes/InfoPlist.html}.
+
+In the NSTypes fields, I used NSIcon (the icon to use for the type)
+NSUnixExtensions (a list of file extensions corresponding to the type)
+and NSRole (what the app can do with documents of this type).  In the
+AppList cache, I generate a dictionary, keyed by file extension, whose
+values are the dictionaries containing the NSTypes dictionaries of each
+of the apps that handle the extension.
+
+I tested the code briefly with the FileViewer app, and it seemed to
+provide the icons as expected.
+
+With this model the software doesn't need to monitor loads of
+different files, just register to recieve notifications when the
+defaults database changes, and check an appropriate default value.  At
+present, there are four hidden files used by the software:
+
+@table @samp
+@item ~/GNUstep/Services/.GNUstepAppList
+	Cached information about applications and file extensions.
+@item ~/GNUstep/Services/.GNUstepExtPrefs
+	User preferences for which apps/icons should be used for each file
+	extension.
+@item ~/GNUstep/Services/.GNUstepServices
+	Cache of services provides by apps and services daemons
+@item ~/GNUstep/Services/.GNUstepDisabled
+	User settings to determine which services should not appear in the
+	services menu.
+@end table 
+
+Each of these is a serialized property list.
+
+Almost forgot - Need to modify NSApplication to understand '-GSOpenFile ...'
+as an instruction to open the specified file on launching.  Need to modify
+NSWorkspace to supply the appropriate arguments when launching a task rather
+than using the existing mechanism of using DO to request that the app opens
+the file.  When these changes are made, we can turn any program into a
+pseudo-GNUstep app by creating the appropriate app wrapper.
+An app wrapper then need only contain a shell-script that understands the
+-GSOpenFile argument and uses it to start the program - though provision of
+a GNUstep-info.plist and various icons would obviously make things prettier.
+
+For instance - you could set up xv.app to contain a shellscript 'xv' that
+would start the real xv binary passing it a file to open if the -GSOpenFile
+argument was given.  The Info-gnustep.plist file could look like this:
+
+@example
+@{
+  NSExecutable = "xv";
+  NSIcon = "xv.tiff";
+  NSTypes = (
+    @{
+      NSIcon = "tiff.tiff";
+      NSUnixExtensions = ( tiff, tif );
+    @},
+    @{
+      NSIcon = "xbm.tiff";
+      NSUnixExtensions = ( xbm );
+    @}
+  );
+@}
+@end example
+
+@section Contributing
+
+Contributing code is not difficult. Here are
+some general guidelines:
+
+@itemize @bullet
+
+@item
+FSF must maintain the right to accept or reject potential contributions.
+Generally, the only reasons for rejecting contributions are cases where
+they duplicate existing or nearly-released code, contain unremovable
+specific machine dependencies, or are somehow incompatible with the
+rest of the library. 
+
+@item
+Acceptance of contributions means that the code is accepted for adaptation
+into libgnustep-gui.  FSF must reserve the right to make various editorial
+changes in code. Very often, this merely entails formatting, maintenance of
+various conventions, etc. Contributors are always given authorship credit and
+shown the final version for approval.
+
+@item
+Contributors must assign their copyright to FSF via a form sent out
+upon acceptance. Assigning copyright to FSF ensures that the code
+may be freely distributed.
+
+@item
+Assistance in providing documentation, test files, and debugging
+support is strongly encouraged.
+
+@end itemize
+
+Extensions, comments, and suggested modifications of existing libgnustep-gui
+features are also very welcome.
+
+@page
+

Documentation/manual/manual.texi

@@ -0,0 +1,105 @@
+\input texinfo              @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename manual.info
+@settitle GNUstep GUI, Programming Manual
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* GNUstepBase:         GNUstep GUI Library (OpenStep AppKit)
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+Copyright @copyright{} 2001 Free Software Foundation
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@setchapternewpage odd
+@titlepage
+
+@title GNUstep GUI Library (OpenStep AppKit)
+@title Programming Manual
+
+@author Adam Fedor (fedor@@gnu.org)
+@author Nicola Pero (n.pero@@mi.flashnet.it)
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2001 Free Software Foundation
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@contents
+
+@ignore : No foreword written yet
+@ifnothtml
+@iftex
+@c Foreword
+@include foreword.texi
+@end iftex
+@end ifnothtml
+@end ignore
+
+@ifinfo
+@c **Top node and master menu
+@node Top
+@top Objective-C Programming Manual
+
+@ignore : No foreword written yet
+@include foreword.texi
+@end ignore
+
+@menu
+* Introduction::	 An introduction to the GNUstep GUI library
+* Basic Classes::	 Basic Classes in the Library
+@end menu
+@c **end Top node and master menu
+@end ifinfo
+
+@page
+
+@c Chapter 1, Introduction
+@include Introduction.texi 
+
+@c Chapter 1, Basic Classes
+@include BasicClasses.texi 
+
+
+@unnumbered Concept Index
+@printindex cp
+
+@bye
+
+
+
+
+
+
+
+