diff options
Diffstat (limited to 'doc/misc.doc')
| -rw-r--r-- | doc/misc.doc | 1127 |
1 files changed, 1127 insertions, 0 deletions
diff --git a/doc/misc.doc b/doc/misc.doc new file mode 100644 index 000000000..bae26156f --- /dev/null +++ b/doc/misc.doc @@ -0,0 +1,1127 @@ +/**************************************************************************** +** +** Miscellaneous documentation that doesn't fit anywhere else +** +** 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 commonproblems.html +\title Brief Technical FAQ + + +This document describes how to use more than one Qt version on one +machine and how to use Qt on X11 without a window manager. In addition +it explains the most common source of link errors with Qt. + +Other frequently asked questions can be found in the +\link http://www.trolltech.com/developer/faqs/ FAQ index\endlink and +in the \link http://www.trolltech.com/developer/faqs/technical.html Technical FAQ\endlink. + +\list +\i \link #linkerror Link error, complaining about a lack of +<tt>vtbl</tt>, <tt>_vtbl</tt>, <tt>__vtbl</tt> or similar\endlink +\i \link #diffver Using different versions of Qt on the same +machine\endlink + \list + \i \link #qtbin Developers building for a single version of Qt on Unix - Qt binary packages\endlink + \i \link #qtsrc Developers building for two versions of Qt on Unix - Qt sources\endlink + \endlist +\i \link #nowinman Using Qt on X11 without a window manager\endlink +\i \link distributingqt.html Distributing Qt Applications\endlink +\endlist + +\target linkerror +\section1 Link error, complaining about a lack of \c vtbl, \c _vtbl, \c __vtbl or similar + +This indicates that you've included the Q_OBJECT macro in a class +declaration and probably also run the moc, but forgot to link the +moc-generated object code into your executable. See \link moc.html +Using the Meta Object Compiler\endlink for details on how to use moc. + +\target diffver +\section1 Using different versions of Qt on the same machine + +Qt programs need the following components of a Qt distribution: + +<dl> + +<dt>Header files - Compile time + +<dd>Programmers need to include the Qt header files. The Qt header files +are usually located in the \c include subdirectory of Qt distributions. +Care must be taken to include the header files of the relevant release of +Qt. Those with a command-line compiler will typically use options such as +\c{/I%QTDIR%\include} or \c{-I"$QTDIR"/include} provided \c QTDIR specifies +the relevant release of Qt. + +<dt>Meta Object Compiler and other tools - Compile time + +<dd>Programmers need to run \e moc and other tools such as \e uic. These +tools are usually located in the \c bin subdirectory of Qt distributions. +Either run \c "$QTDIR"/bin/moc and \c "$QTDIR"/bin/uic or add \c "$QTDIR"/bin +to your \c PATH and run \c moc and \c uic. If you use \c qmake the +appropriate lines will be added to your Makefiles so that \e uic and +\e moc will be executed as retquired. + +<dt>Static or shared libraries - Link time + +<dd>Programmers need to link with the Qt static or shared libraries. The Qt +libraries are usually located in the \c lib subdirectory of Qt distributions. +Care must be taken to link with the libraries of the relevant release of +Qt. Those with a command-line compiler will typically use options such as +\c{/L%QTDIR%\lib\qt.lib} or \c{-L"$QTDIR"/lib} \c -lqt provided \c QTDIR +specifies the relevant release of Qt. + +<dt>Shared libraries - Run time + +<dd>Users of programs linked with shared Qt libraries need these same +shared libraries to run these programs. The Qt libraries are usually +located in the \c lib subdirectory of Qt distributions. Shared libraries +are made available to programs in places such as \c{C:\windows\system} on +Windows platforms, directories listed in file \c /etc/ld.so.conf on Linux, +standard \c lib directories on Unix, or directories listed in environment +variables \c LD_LIBRARY_PATH, \c SHLIB_PATH, or \c LIBPATH on various Unix +flavours. Make the relevant Qt libraries available using one of these +mechanisms. + +</dl> + +Qt distributions consist of different files needed at compile time, +link time, or run time. Trolltech distributes Qt in the form of a +source package that contain all these files once they have been built. + +Other vendors distribute Qt in the form of binary packages. Binary packages +usually consist of two parts: + +\list +\i shared libraries in the run time package, usually called \c qt3. + +\i header files, static libraries, the moc and other tools in the developers' +kit, usually called \c qt3-dev. + +\endlist + +Depending on how you are using Qt, you need to make specific parts of +the Qt distribution available to your programs. Typical situations are +described below. + +\target qtbin +\section2 Developers building for a single version of Qt on Unix - Qt binary packages + +You build programs with a single version of Qt, but you still need +to run programs linked with another version of Qt. You are typically +a Linux developer who builds programs for Qt 3.x on a KDE desktop based +on Qt 2.x. Qt packages are usually split into a shared library +package with a name like \c qt and a developer package with a name +like \c qt-dev. You will need the appropriate packages: + +\list + +\i To build programs you will need the header files, the libraries, +the moc and other tools from Qt 3.x. They are included in the developer +package of Qt 3.x (\c qt3-dev or similar). + +\i To run programs you will need the shared libraries of Qt 3.x and +Qt 2.x. They are included in the regular packages of Qt 3.x (\c qt3 +or similar) and Qt 2.x (\c qt2 or similar). + +\endlist + +Just install the packages, \c qt2, \c qt3, and \c qt3-dev. You may +need to set the environment variable \c QTDIR to point to Qt 3.x. + +\target qtsrc +\section2 Developers building for two versions of Qt on Unix - Qt sources + +You build and run programs for Qt 2.x and Qt 3.x. You will need: + +\list + +\i the header files, the libraries, the moc and other tools from Qt 3.x +and Qt 2.x to build programs, + +\i the shared libraries of Qt 3.x and Qt 2.x to run programs. + +\endlist + +Get the source distributions of both Qt 2.x and Qt 3.x. + +\list 1 + +\i Install and build Qt 2.x and Qt 3.x, usually in \c /opt or +\c /usr/local. In the case of \c /opt: + +\code +$ cd /opt +$ gunzip -c \c qt-x11-2.3.1.tar.gz | tar xf - +$ cd qt-2.3.1 +$ setenv QTDIR /opt/qt-2.3.1 +$ configure [options] +$ make + +$ cd /opt +$ gunzip -c qt-x11-free-3.0.0.tar.gz | tar xf - +$ cd qt-3.0.0 +$ setenv QTDIR /opt/qt-3.0.0 +$ configure [options] +$ make +\endcode + +\i Make shared libraries available to programs at run time. Either +add both \c /opt/qt-2.3.1/lib and \c /opt/qt-3.0.0/lib to your environment +variable \c LD_LIBRARY_PATH or file \c /etc/ld.so.conf or whataver mechanism +you're using, or make links to the libraries in a standard directory like +\c /usr/local/lib: + +\code +cd /usr/local/lib +ln -s /opt/qt-2.3.1/lib/libqt.so.2 . +ln -s /opt/qt-2.3.1/lib/libtqt-mt.so.2 . +ln -s /opt/qt-2.3.1/lib/libqutil.so.1 . +ln -s /opt/qt-3.0.0/lib/libqt.so.3 . +ln -s /opt/qt-3.0.0/lib/libtqui.so.1 . +\endcode + +\endlist + +To develop with Qt 2.x use: + +\code +setenv QTDIR /opt/qt-2.3.1 +setenv PATH ${QTDIR}/bin:${PATH} +\endcode + +To develop with Qt 3.x use: + +\code +setenv QTDIR /opt/qt-3.0.0 +setenv PATH ${QTDIR}/bin:${PATH} +\endcode + +Setting \c QTDIR ensures that the proper resources are used, such as the +documentation appropriate to the version of Qt you're using. Also +your Makfiles may refer to \c "$QTDIR"/include and \c "$QTDIR"/lib to +include the proper header files and link with the proper libraries. +Setting the \c PATH ensures that the proper version of moc and other +tools is being used. + +\target nowinman +\section1 Using Qt on X11 without a window manager + +When using Qt without a window manager on Unix/X11, you will most +likely experience focus problems. Without a window manager, there is +no focus handling on X11, and no concept of an active window +either. If you want your application to work in such an environment, +you have to explicitly mark a window as active \e after showing it: + +\code + yourWindow->show(); + yourWindow->setActiveWindow(); +\endcode + +Note that setActiveWindow() won't work if the widget does not become +physically visible during this event cycle. However, without a window +manager running, this is guaranteed to happen. For the curious reader: +setActiveWindow() emulates a window manager by explicitly setting the +X Input Focus to a widget's top level window. + +*/ + +/*! \page bughowto.html +\title How to Report A Bug + +If you think you have found a bug in Qt, we would like to hear +about it so that we can fix it. + +Before reporting a bug, please check the +\link commonproblems.html Brief Technical FAQ\endlink, the +\link http://www.trolltech.com/developer/faqs/ FAQs\endlink, and the +\link http://www.trolltech.com/platforms/ Platform Notes\endlink +on our web site to see if the issue is already known. + +Always include the following information in your bug report: + +\list 1 +\i The name and version number of your compiler +\i The name and version number of your operating system +\i The version of Qt you are using, and what configure options it was +compiled with. +\endlist + +If the problem you are reporting is only at visible run-time, try to +create a small test program that shows the problem when run. Often, +such a program can be created with some minor changes to one +of the many example programs in the \c{qt/examples} directory. + +Please send the bug report to +\link mailto:qt-bugs@trolltech.com qt-bugs@trolltech.com\endlink. +*/ + + + + +/*! \page license.html + +\title Qt Open Source Edition License Agreement + +The Qt Open Source Edition is distributed under the Q Public License (QPL). +It allows free use of Qt Open Source Edition for running software developed by +others, and free use of Qt Open Source Edition for development of free and open source +software. There is \link http://www.trolltech.com/qpl/ more information +about the QPL\endlink at the Trolltech web site. + +Note that the Qt/Embedded Open Source Edition is <b>not</b> distributed +under the QPL, but under the \link gpl.html GNU General Public +License (GPL)\endlink. + +For development non-free/proprietary software, the Qt Professional +Edition is available. It has a normal commercial library license, with +none of the special restrictions of the QPL or the GPL. + +<hr> + +<center> +<h2> +THE Q PUBLIC LICENSE +version 1.0 +</h2> +<b> +Copyright (C) 1999-2008 Trolltech ASA, Norway.<br> +Everyone is permitted to copy and distribute this license document. +</b> +</center> + +The intent of this license is to establish freedom to share and change the +software regulated by this license under the open source model. + +This license applies to any software containing a notice placed by the +copyright holder saying that it may be distributed under the terms of +the Q Public License version 1.0. Such software is herein referred to as +the Software. This license covers modification and distribution of the +Software, use of third-party application programs based on the Software, +and development of free software which uses the Software. + + +<h3 align="center"> + Granted Rights +</h3> + +1. You are granted the non-exclusive rights set forth in this license + provided you agree to and comply with any and all conditions in this + license. Whole or partial distribution of the Software, or software + items that link with the Software, in any form signifies acceptance of + this license. + +2. You may copy and distribute the Software in unmodified form provided + that the entire package, including - but not restricted to - copyright, + trademark notices and disclaimers, as released by the initial developer + of the Software, is distributed. + +3. You may make modifications to the Software and distribute your + modifications, in a form that is separate from the Software, such as + patches. The following restrictions apply to modifications: + +<blockquote> + a. Modifications must not alter or remove any copyright notices in + the Software. + + b. When modifications to the Software are released under this + license, a non-exclusive royalty-free right is granted to the + initial developer of the Software to distribute your modification + in future versions of the Software provided such versions remain + available under these terms in addition to any other license(s) of + the initial developer. +</blockquote> + +4. You may distribute machine-executable forms of the Software or + machine-executable forms of modified versions of the Software, provided + that you meet these restrictions: + +<blockquote> + a. You must include this license document in the distribution. + + b. You must ensure that all recipients of the machine-executable forms + are also able to receive the complete machine-readable source code + to the distributed Software, including all modifications, without + any charge beyond the costs of data transfer, and place prominent + notices in the distribution explaining this. + + c. You must ensure that all modifications included in the + machine-executable forms are available under the terms of this + license. + +</blockquote> + +5. You may use the original or modified versions of the Software to + compile, link and run application programs legally developed by you + or by others. + +6. You may develop application programs, reusable components and other + software items that link with the original or modified versions of the + Software. These items, when distributed, are subject to the following + retquirements: + +<blockquote> + a. You must ensure that all recipients of machine-executable forms of + these items are also able to receive and use the complete + machine-readable source code to the items without any charge + beyond the costs of data transfer. + + b. You must explicitly license all recipients of your items to use + and re-distribute original and modified versions of the items in + both machine-executable and source code forms. The recipients must + be able to do so without any charges whatsoever, and they must be + able to re-distribute to anyone they choose. + + c. If the items are not available to the general public, and the + initial developer of the Software requests a copy of the items, + then you must supply one. +</blockquote> + + +<h3 align="center"> + Limitations of Liability +</h3> + +In no event shall the initial developers or copyright holders be liable +for any damages whatsoever, including - but not restricted to - lost +revenue or profits or other direct, indirect, special, incidental or +consequential damages, even if they have been advised of the possibility +of such damages, except to the extent invariable law, if any, provides +otherwise. + + +<h3 align="center"> + No Warranty +</h3> + +The Software and this license document are provided AS IS with NO WARRANTY +OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE. + +<h3 align="center"> + Choice of Law +</h3> + +This license is governed by the Laws of Norway. Disputes shall be settled +by Oslo City Court. + +*/ + + +/*! \page gpl.html +\title GNU General Public License + + The Qt GUI Toolkit is Copyright (C) 1994-2008 Trolltech ASA. + + The Qt Open Source Edition and the Qt/Embedded Open Source Edition are available + under the GPL. The Qt Open Source Edition (for Unix/X11) is also available + under the \link license.html QPL\endlink. + +\code + You may use, distribute and copy the Qt GUI Toolkit under the terms of + GNU General Public License version 2, which is displayed below. + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Steet, Fifth Floor, Boston, MA 02110-1301, USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not retquired to print an announcement.) + +These retquirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not retquired to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Steet, Fifth Floor, + Boston, MA 02110-1301, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. +\endcode +*/ + + + +/*! \page troll.html + +\title Company Information + +Trolltech is an international software company with +headquarters in Oslo, the capital of Norway, and with offices +in Brisbane, Australia, and Redwood City, California. + +Our flagship product is \link +http://www.trolltech.com/products/qt.html Qt\endlink, the +multi-platform C++ GUI toolkit. Qt enables you to build professional, +efficient, portable and maintainable GUI applications tquickly and +easily. + +\link http://www.trolltech.com/products/embedded/index.html +Qt/Embedded\endlink, the embedded version of Qt, is designed to power +todays new generation of embedded computers and electronic consumer +devices. On top of that, \link +http://www.trolltech.com/products/qtopia/index.html Qtopia\endlink +provides a window system and application suite for handheld devices. + +\section1 Software that makes Sense + +Our motto expresses the vision behind our products. We design our +products to give our customers the feeling of "this is the way +that things were always meant to be". + +We know that it is crucial for our customers to have good tools for +making good software. Therefore, we do not compromise our demands for +superior design and technical quality when we develop our +products. + +Trolltech is also known for providing top quality technical support +to our customers. At Trolltech, support intquiries are handled by the +most qualified developers and designers themselves. + +\section1 History + +Trolltech was founded in 1994. The core team of designers at Trolltech +started developing Qt in 1992, and the first commercial version of Qt was +released in 1995. Since then, Trolltech has experienced rapid growth, and +Qt is currently used in thousands of successful commercial software +development projects world wide. At Trolltech, we continously work to +improve and expand Qt to ensure that it always represents the state of the +art in usability, look and feel, performance, and stability. + +For more information, please visit the \link http://www.trolltech.com +Trolltech website\endlink. + +\section1 Contact Information + +<br clear="all"> + +<table cellpadding=3 cellspacing=0 border="0" bgcolor="#E5E5E5"> +<tr><th colspan=6 valign="top" bgcolor="#a2c511">Email</th></tr> +<tr> +<td rowspan=4><br></td> +<td colspan=2>\link mailto:info@trolltech.com <strong>info@trolltech.com</strong>\endlink + +<td colspan=2>\link mailto:sales@trolltech.com <strong>sales@trolltech.com</strong>\endlink +<td rowspan=4><br></td> +<tr> +<td ><br></td> +<td valign="top"> General intquiries and questions. Please check the +\link http://www.trolltech.com/faq/ FAQ\endlink to see if your question is already answered there.</td> +<td ><br></td> +<td valign="top"> Intquires related to purchasing, pricing and availability of +Trolltech products</td></tr> +<tr> +<td colspan=2>\link mailto:www@trolltech.com <strong>www@trolltech.com</strong>\endlink +<td colspan=2>\link mailto:qt-bugs@trolltech.com <strong>qt-bugs@trolltech.com</strong>\endlink +<tr> +<td ><br></td> +<td valign="top"> Comments about our web pages</td> +<td ><br></td> +<td valign="top"> +Use this address for bug reports; \e please read (the very short) +\link bughowto.html How to Report a Bug\endlink page \e first. +</td></tr> +<tr><td ><br></td> +<td colspan=4 valign="top">Note that Trolltech uses the +\link http://mail-abuse.org/rbl/ RBL\endlink and +\link http://work-rss.mail-abuse.org/rss/ RSS\endlink databases to cut down on +spam. If your mail server is listed, you will regrettably not be able to +send us mail. The \link http://www.mail-abuse.org/tsi/ MAPS TSI\endlink +pages provide information about how to secure your server. +</td><td ><br></td></tr> +<tr bgcolor="#ffffff"><td bgcolor="#ffffff" colspan="6"> <br> </td></tr> +<tr><th colspan=6 valign="top" bgcolor="#a2c511">Norway Office</th></tr> +</tr> +<tr> +<td rowspan=4><br></td> +<td colspan=2><strong>Telephone</strong> +<td colspan=2><strong>Street/Mail Address</strong> +<td rowspan=4><br></td> +<tr> +<td ><br></td> +<td valign="top"> General intquiries: +47 21 60 48 00</td> +<td rowspan=3><br></td> +<td valign="top" rowspan=3> Sandakerveien 116<br> PO Box 4332 Nydalen<br> NO-0402 Oslo<br> Norway</td></tr> +<tr> +<td colspan=2><strong>Telefax</strong></td> +<tr> +<td ><br></td> +<td valign="top"> All intquiries: +47 21 60 48 01</td> +<tr bgcolor="#ffffff"><td bgcolor="#ffffff" colspan="6"> <br> </td></tr> +<tr><th colspan=6 valign="top" bgcolor="#a2c511">USA Office</th></tr> +</tr> +<tr> +<td rowspan=4><br></td> +<td colspan=2><strong>Telephone</strong> +<td colspan=2><strong>Street/Mail Address</strong> +<td rowspan=4><br></td> +<tr> +<td ><br></td> +<td valign="top"> General intquiries: (+1) 650-551-1676</td> +<td rowspan=3><br></td> +<td valign="top" rowspan=3> 555 Twin Dolphin Drive<br> Suite 280<br> Redwood City, CA 94065<br> USA</td></tr> +<tr> +<td colspan=2><strong>Telefax</strong></td> +<tr> +<td ><br></td> +<td valign="top"> All intquiries: (+1) 650-551-1851</td> +</table> + +*/ + + +/*! \page guibooks.html + +\title Books about GUI + +This is not a comprehensive list of books, there are many other +books worth buying. Here we mention just a few GUI/UI books that don't +gather dust in our shelves. + +<b>C++ GUI Programming with Qt 3</b> by Jasmin Blanchette and Mark +Summerfield, ISBN 0-13-124072-2. This is the Official Qt book written +by two veteran Trolls. +\link http://www.amazon.com/exec/obidos/ASIN/0131240722/trolltech/ +(Read more about it or buy it.)\endlink + +<b>The Design of Everyday Things</b> by Donald Norman, +ISBN 0-38526774-6, is one of the classics of human interface design. +Norman shows how badly something as simple as a kitchen stove can be +designed, and everyone should read it who will design a dialog box, +write an error message, or design just about anything else humans are +supposed to use. +\link http://www.amazon.com/exec/obidos/ASIN/0385267746/trolltech/t +(Read more or buy it.)\endlink + +\target fowler +<b>GUI Design Handbook</b> by Susan Fowler, ISBN 0-07-059274-8, is an +alphabetical dictionary of widgets and other user interface elements, +with comprehensive coverage of each. Each chapter covers one widget +or other element, contains the most important recommendation from the +Macintosh, Windows and Motif style guides, notes about common +problems, comparison with other widgets that can serve some of the +same roles as this one, etc. + +\link http://www.amazon.com/exec/obidos/ASIN/0070592748/trolltech/t +(Read more or buy it.)\endlink + +<b>Macintosh Human Interface Guidelines</b>, second edition, ISBN +0-201-62216-5, is worth buying for the \e {don't}s alone. Even +though you're not writing Macintosh software, avoiding most of what it +advises against will produce more easily comprehensible software. +Doing what it tells you to \e do helps, too. +\link http://www.amazon.com/exec/obidos/ASIN/0201622165/trolltech/t +(Read more or buy it.)\endlink + +This book is now available +\link http://developer.apple.com/techpubs/mac/HIGuidelines/HIGuidelines-2.html +on the web\endlink and there is a +\link http://developer.apple.com/techpubs/mac/HIGOS8Guide/thig-2.html Mac +OS 8 addendum.\endlink + +<b>The Microsoft Windows User Experience</b>, ISBN 1-55615-679-0, +is Microsoft's look and feel Bible. Indispensable for everyone who +has customers that worship Microsoft, and it's tquite good, too. +\link http://www.amazon.com/exec/obidos/ASIN/0735605661/trolltech/t +(Read more or buy it.)\endlink + +Microsoft's guidelines are often available on the web, but have +occasionally been hidden in an impenetrable maze of javascript. +\link http://msdn.microsoft.com/library/en-us/dnwue/html/welcome.asp Try and see.\endlink + +<b>The Icon Book</b> by William Horton, ISBN 0-471-59900-X, is a +perhaps the only thorough coverage of icons and icon use in software. +In order for icons to be successful, people must be able to do four +things with them: decode, recognize, find and activate them. This +book explains these goals from scratch and how to reach them, both +with single icons and icon families. Some 500 examples are scattered +throughout the text, generally in groups of four or five. +\link http://www.amazon.com/exec/obidos/ASIN/047159900X/trolltech/t +(Read more or buy it.)\endlink + +\section1 <nobr>Buying these books from</nobr> +\link http://www.amazon.com/text/ Amazon.com.\endlink + +These books are made available in association with Amazon.com, our +favorite on-line bookstore. Here is more information about +\link http://www.amazon.com/exec/obidos/subst/help/shipping-policy.html/t +Amazon.com's shipping options\endlink and its +\link http://www.amazon.com/exec/obidos/subst/help/desk.html/t +customer service.\endlink When you buy a book by following one of these +links, Amazon.com gives about 15% of the purchase price to +\link http://www.amnesty.org Amnesty International.\endlink + +*/ + + +/*! \page licenses.html +\title Licenses for Code Used in Qt + +Qt contains a little code that is not under the \link license.html +QPL\endlink, the \link gpl.html GPL\endlink, or the Qt Commercial +License Agreement, but rather under specific highly permissive +licenses from the original authors. This page lists the licenses used +for that code, names the authors, and links to the points where it is +used. + +Trolltech gratefully acknowledges these and others contribution to +Qt. We recommend that all programs that use Qt also acknowledge these +contributions, and quote all these license statements in an appendix +to the documentation. + +\legaleselist + +*/ + + +/*! \page geometry.html +\title Window Geometry + +\section1 Overview + +QWidget provides several functions that deal with a widget's +geometry. Some of these functions operate on the pure client area +(i.e. the window excluding the window frame), others include the +window frame. The differentiation is done in a way that covers the +most common usage transparently. + +\table +\row +\i <strong>Including the window frame: +\i x(), y(), frameGeometry(), pos() and move() +\row +\i <strong>Excluding the window frame:</strong> +\i geometry(), width(), height(), rect() and size() +\endtable + +Note that the distinction only matters for decorated top-level +widgets. For all child widgets, the frame geometry is equal to the +widget's client geometry. + +This diagram shows most of the functions in use: +\img geometry.png Geometry diagram + +\section1 Unix/X11 peculiarities + +On Unix/X11, a window does not have a frame until the window manager +decorates it. This happens asynchronously at some point in time after +calling show() and the first paint event the window receives: or it +does not happen at all. Bear in mind that X11 is policy-free (others +call it flexible). Thus you cannot make any safe assumption about the +decoration frame your window will get. Basic rule: there's always one +user who uses a window manager that breaks your assumption, and who +will complain to you. + +Furthermore, a toolkit cannot simply place windows on the screen. All +Qt can do is to send certain hints to the window manager. The window +manager, a separate process, may either obey, ignore or misunderstand +them. Due to the partially unclear Inter-Client Communication +Conventions Manual (ICCCM), window placement is handled tquite +differently in existing window managers. + +X11 provides no standard or easy way to get the frame geometry once +the window is decorated. Qt solves this problem with nifty heuristics +and clever code that works on a wide range of window managers that +exist today. Don't be surprised if you find one where frameGeometry() +returns bogus results though. + +Nor does X11 provide a way to maximize a window. The showMaximized() +function in Qt therefore has to emulate the feature. Its result +depends on the result of frameGeometry() and the capability of the +window manager to do proper window placement, neither of which can be +guaranteed. + +\section1 Restoring a Window's Geometry + +A common task in modern applications is to restore a window's geometry +in a later session. On Windows, this is basically storing the result +of geometry() and calling setGeometry() in the next session before +calling show(). On X11, this won't work because an invisible window +doesn't have a frame yet. The window manager would decorate the window +later. When this happens, the window shifts towards the bottom/right +corner of the screen depending on the size of the decoration frame. X +theoretically provides a way to avoid this shift. Our tests have +shown, though, that almost all window managers fail to implement this +feature. + +A workaround is to call setGeometry() after show(). This has the +two disadvantages that the widget appears at a wrong place for a +millisecond (results in flashing) and that currently only every +second window manager gets it right. A safer solution is to store +both pos() and size() and to restore the geometry using resize() and +move() before calling show(), as demonstrated in the following +example: + +\code + MyWidget* widget = new MyWidget + ... + QPoint p = widget->pos(); // store position + QSize s = widget->size(); // store size + ... + widget = new MyWidget; + widget->resize( s ); // restore size + widget->move( p ); // restore position + widget->show(); // show widget +\endcode + +This method works on both MS-Windows and most existing X11 window +managers. + +*/ |