You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
341 lines
14 KiB
341 lines
14 KiB
/****************************************************************************
|
|
**
|
|
** 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).
|
|
|
|
*/
|