diff options
Diffstat (limited to 'doc/embclasses.doc')
| -rw-r--r-- | doc/embclasses.doc | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/doc/embclasses.doc b/doc/embclasses.doc deleted file mode 100644 index b88befdae..000000000 --- a/doc/embclasses.doc +++ /dev/null @@ -1,340 +0,0 @@ -/**************************************************************************** -** -** A brief guide to the Qt/Embedded internal classes -** -** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. -** -** This file is part of the TQt 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 TQt 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 $TQTDIR/etc/fonts/fontdir (or \c -/usr/local/etc/qt-embedded/fonts/fontdir if TQTDIR 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). - -*/ |