1 files changed, 340 insertions, 0 deletions

diff --git a/doc/embclasses.doc b/doc/embclasses.doc
new file mode 100644
index 000000000..99d98b1b0
--- /dev/null
+++ b/doc/embclasses.doc
@@ -0,0 +1,340 @@
+/****************************************************************************
+**
+** A brief guide to the Qt/Embedded internal classes
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing retquirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+\page emb-classes.html
+
+\title The Qt/Embedded-specific classes
+
+Qt/Embedded classes fall into two groups: the majority are used by
+every Qt/Embedded program, and some are used only by the Qt/Embedded server. 
+The Qt/Embedded server program can also be a client, as in the case of a
+single-process installation. All Qt/Embedded specific source files live
+in \c src/kernel and are suffixed \c{_qws}. The » symbol
+indicates inheritance.
+
+\tableofcontents
+
+\section1 QFontManager
+
+There is one of these per application. At application startup time it
+reads the font definition file from \c $QTDIR/etc/fonts/fontdir (or \c
+/usr/local/etc/qt-embedded/fonts/fontdir if QTDIR is undefined). It
+keeps track of all font information and maintains a cache of rendered
+fonts. It also creates the font factories: QFontManager::QFontManager
+is the place to add constructors for new factories. It provides a
+high-level interface for requesting a particular font and calls
+QFontFactories to load fonts from disk on demand. Note that this only
+applies to BDF and TrueType fonts; Qt/Embedded's optimised \c .qpf
+font file format bypasses the QFontManager mechanism altogether. 
+
+There should be no need to modify this class unless you wish to change
+font matching or caching behaviour.
+
+\section1 QDiskFont
+
+This contains information about a single on-disk font file (e.g.
+\c{/usr/local/etc/qt-embedded/times.ttf}). It holds the file path,
+information about whether the font is scalable, its weight, size,
+Qt/Embedded name, etc. This information is used so that QFontManager
+can find the closest matching disk font (it uses a scoring mechanism
+weighted towards matching names, then whether the font's italic, then
+its weight). 
+
+There should be no reason to modify this class.
+
+\section1 QRenderedFont
+
+There is one and only one QRenderedFont for every unique font
+currently loaded by the system (that is, each unique combination of
+name, size, weight, italic or not, anti-aliased or not).
+QRenderedFonts are reference counted; once no one is using the
+QRenderedFont it is deleted along with its cache of glyph bitmaps. The
+QDiskFont it was loaded from remains opened by its QFontFactory.
+
+There should be no reason to modify this class, unless you wish to
+change the way in which glyphs are cached.
+
+
+\section1 QFontFactory (and descendants QFontFactoryBDF, QFontFactoryTtf)
+
+These provide support for particular font formats, for instance the
+scalable Truetype and Type1 formats (both supported in
+QFontFactoryTtf, which uses Freetype 2) and the bitmap BDF format used
+by X. It's called to open an on-disk font; once a font is opened it
+remains opened so that the creation of new font instances from the
+disk font is fast. It can also create a QRenderedFont and convert from
+Unicode values to an index into the font file. For compactness, glyphs
+are stored in the order and indexes they are defined in the font
+rather than in Unicode order. 
+
+There should be no need to modify this class, but it should be
+inherited if you wish to add a different type of font renderer (e.g.
+for a custom vector font format).
+
+\section1 QGlyph
+
+This describes a particular image of a character from a QRenderedFont:
+for example, the letter 'A' at 10 points in Times New Roman, bold italic,
+anti-aliased. It contains pointers to a QGlyphMetrics structure with
+information about the character and to the raw data for the glyph:
+this is either a 1-bit mask or an 8-bit alpha channel. Each QRenderedFont
+creates these on demand and caches them once created (note that this is
+not currently implemented for TrueType fonts). 
+
+You would only need to modify this class if you were, for example,
+modifying Qt/Embedded to support textured fonts, in which case you
+would also need to modify QGfxRaster.
+
+\section1 QMemoryManagerPixmap/QMemoryManager
+
+This handles requests for space for pixmaps and also keeps track of
+QPF format fonts (these are small 'state dumps' of QRenderedFonts,
+typically 2-20KB in size; they can be mmap'd direct from disk in order
+to save memory). If a QPF font is found which matches a font request
+no new QRenderedFont need be created for it. It's possible to strip out
+all QFontFactory support and simply use QPFs if your font needs are modest
+(for instance, if you only retquire a few fixed point sizes). Note that
+no best-match loading is performed with QPFs, as opposed to those
+loaded via QFontManager, so if you don't have the correct QPF for a point
+size, text in that size will simply not be displayed. 
+
+There should be no need to modify this class.
+
+\section1 QScreen » QLinuxFbScreen » accelerated screens, QTransformedScreen » QVfbScreen
+
+These encapsulate the framebuffer Qt/Embedded is drawing to, provide
+support for mapping of coordinates for rotating framebuffers, allow
+manipulation of the colour palette and provide access to offscreen
+graphics memory for devices with separate framebuffer memories.
+
+This is used for caching pixmaps and allowing accelerated pixmap=\>screen
+blt's. QLinuxFbScreen and the accelerated screens use the Linux \c /dev/fb
+interface to get access to graphics memory and information about the
+characteristics of the device. The framebuffer device to open is specified
+by QWS_DISPLAY. Only QTransformedScreen implements the support for rotated
+framebuffers. QVfbScreen provides an X window containing an emulated
+framebuffer (a chunk of shared memory is set aside as the 'framebuffer'
+and blt'd into the X window): this is intended as a debugging device
+allowing users to debug their applications under Qt/Embedded without leaving 
+X. The accelerated screen drivers check to see if they can drive the
+device specified by QWS_CARD_SLOT (which defaults to the usual position
+of an AGP slot if not specified) and mmap its on-chip registers from
+\c /dev/mem. They may also do chip-specific setup (initialising registers to
+known values and so on). Finally, QScreen's are used to create new
+QScreenCursors and QGfxes. 
+
+If you wish to modify the way pixmaps are allocated in memory,
+subclass or modify QLinuxFbScreen. If you're writing an accelerated
+driver you will need to subclass QScreen or QLinuxFbScreen.
+
+\section1 QScreenCursor » accelerated cursor » QVfbCursor
+
+This handles drawing the on-screen mouse cursor, and saving and
+restoring the screen under it for the non-accelerated cursor types.
+
+Subclassing QScreenCursor is optional in an accelerated driver (you
+would only want to do so if the hardware supports a hardware cursor).
+
+\section1 QGfx » RasterBase » Raster » accelerated driver » QGfxVfb » QGfxTransformedRaster
+
+This class encapsulates drawing operations, a little like a low-level
+QPainter. QGfxRaster and its descendants are specifically intended
+for drawing into a raw framebuffer. They can take an offset for drawing
+operations and a clipping region in order to support drawing into windows.
+You will need to subclass the QGfxRaster template in order to implement
+an accelerated driver. 
+
+If you're brave, modifying QGfxRaster would allow you to customise how
+drawing is done or add support for a new bit depth/pixel format.
+
+\section1 QLock, QLockHolder
+
+This encapsulates a System V semaphore, used for synchronising access
+to memory shared between Qt/Embedded clients. QLockHolder is a utility class
+to make managing and destroying QLocks easier. 
+
+There should be no need to modify this class unless porting
+Qt/Embedded to an operating system without System V IPC.
+
+\section1 QDirectPainter
+
+This is a QPainter which also gives you a pointer to the framebuffer
+of the window it's pointing to, the window's clip region and so on.
+It's intended to easily allow you to do your own pixel-level manipulation
+of window contents. 
+
+There should be no reason to modify this class.
+
+\section1 QWSSoundServer, Client
+
+The Qt/Embedded server contains a simple sound player and mixer. Clients
+can request the server play sounds specified as files. 
+
+There should be no need to modify this class unless porting
+Qt/Embedded to an operating system without a Linux-style \c /dev/dsp.
+
+\section1 QWSWindow
+
+This contains the server's notion of an individual top level window:
+the region of the framebuffer it's allocated, the client that created it
+and so forth. 
+
+There should be no reason to modify this class.
+
+\section1 QWSKeyboardHandler » subtypes
+
+This handles keyboard/button input. QWSKeyboardHandler is subclassed
+to provide for reading \c /dev/tty, an arbitrary low-level USB event device
+(for USB keyboards) and some PDA button devices. 
+
+Modifying QWSKeyboardHandler would allow you to support different
+types of keyboard (currently only a fairly standard US PC style
+keyboard is supported); subclassing it is the preferred way to handle
+non-pointer input devices.
+
+\section1 QWSMouseHandler » QWSCalibratedMouseHandler » mouse types
+
+This handles mouse/touch-panel input. Descendants of QWSCalibratedMouseHandler
+make use of filtering code which prevents 'jittering' of the pointer on
+touchscreens; some embedded devices do this filtering in the kernel in
+which case the driver doesn't need to inherit from QWSCalibratedMouseHandler.
+
+Subclassing QWSCalibratedMouseHandler is preferred for touch-panels without
+kernel filtering; inheriting QWSMouseHandler is the way to add any other
+type of pointing device (pen tablets, touchscreens, mice, trackballs
+and so forth).
+
+\section1 QWSDisplay
+
+This class exists only in the Qt/Embedded server and keeps track of
+all the top-level windows in the system, as well as the keyboard and mouse.
+
+You would only want to modify this if making deep and drastic
+modifications to Qt/Embedded window behaviour (alpha blended windows
+for example).
+
+\section1 QWSServer 
+
+This manages the Qt/Embedded server's Unix-domain socket connections to
+clients. It sends and receives QWS protocol events and calls QWSDisplay
+in order to do such things as change the allocation region of windows.
+
+The only reason to modify this would be to use something other than
+some sort of socket-like mechanism to communicate between Qt/Embedded
+applications (in which case modify QWSClient too). If you have
+something like Unix domain sockets, modify QWSSocket/QWSServerSocket
+instead. Don't add extra QWS events to communicate between
+applications, use QCOP instead.
+
+\section1 QWSClient
+
+This encapsulates the client side of a Qt/Embedded connection and can
+marshal and demarshal events. 
+
+There should be no reason to modify this except to use something
+radically different from Unix domain sockets to communicate between
+Qt/Embedded applications.
+
+\section1 QWSDisplayData
+
+This manages a client's QWSClient, reading and interpreting events
+from the QWS server. It connects to the QWS server on application
+startup, getting information about the framebuffer and creating the
+memory manager. Other information about the framebuffer comes directly
+from \c /dev/fb in QLinuxFbScreen. 
+
+There should be no reason to modify this.
+
+\section1 QWSCommands
+
+These encapsulate the data sent to and from the QWS server. 
+
+There should be no reason to modify them.
+
+\section1 QCopChannel
+
+QCop is a simple IPC mechanism for communication between Qt/Embedded
+applications. String messages with optional binary data can be sent
+to different channels. 
+
+The mechanism itself is designed to be bare-bones in order for users
+to build whatever mechanism they like on top of it.
+
+\section1 QWSManager
+
+This provides Qt/Embedded window management, drawing a title bar
+and handling user requests to move, resize the window and so on.
+
+There should be no reason to modify it but you should subclass it
+if you want to modify window behaviour (point to click versus
+focus follows mouse, for instance).
+
+\section1 QWSDecoration
+
+Descendants of this class are different styles for the Qt/Embedded
+window manager, for instance QWSWindowsDecoration draws Qt/Embedded
+window frames in the style of Windows CE. 
+
+Subclass it in order to provide a new window manager appearance (the
+equivalent of a Windows XP or Enlightenment theme).
+
+\section1 QWSPropertyManager
+
+This provides the QWS client's interface to the QWS property system
+(a simpler version of the X property system, it allows you to attach
+arbitrary data to top-level windows, keyed by an integer). 
+
+There should be no reason to modify it.
+
+\section1 QWSRegionManager
+
+Used by both client and server to help manage top-level window regions.
+
+There should be no reason to modify it.
+
+\section1 QWSSocket, QWSServerSocket
+
+Provides Unix-domain sockets. 
+
+Modify this if you're porting to a non-Unix OS but have something
+analogous to Unix-domain sockets (a byte-oriented, reliable, ordered
+transmission mechanism, although you can probably implement it with
+something like a message queue as well).
+
+*/