diff options
Diffstat (limited to 'doc/embclasses.doc')
| -rw-r--r-- | doc/embclasses.doc | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/doc/embclasses.doc b/doc/embclasses.doc new file mode 100644 index 0000000..f043081 --- /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 requirements 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 require 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). + +*/ |