Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 269 insertions, 0 deletions

diff --git a/doc/mac.doc b/doc/mac.doc
new file mode 100644
index 000000000..56bf0b159
--- /dev/null
+++ b/doc/mac.doc
@@ -0,0 +1,269 @@
+/****************************************************************************
+**
+** Qt/Mac documentation
+**
+** Copyright (C) 2002-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 mac-differences.html
+
+\title Qt/Mac Issues
+
+This file will outline known issues and possible workarounds for
+limitations on Mac OS X with Qt. This list will not always be complete, so
+please contact Trolltech support with issues you find to be missing.
+
+See also the document \link qtmac-as-native.html Qt/Mac is Mac OS X
+Native\endlink.
+
+\tableofcontents
+
+\section1 GUI Applications
+
+GUI Applications must be run out of a bundle (something like widgets.app/)
+or using the open(1) command. Mac OS X needs this to dispatch events correctly,
+as well as gaining access to the menubar. If using GDB you must run with the 
+full path to the executable.
+
+\section1 QCursor
+
+Due to Mac OS X having only 16x16 custom cursors QCursor is limited by this
+as well. For now the only workaround to this problem is to use a small
+cursor (16x16).
+
+\section1 Anti-aliased text
+
+Qt/Mac (starting with 3.0.5) has introduced some support for smooth text as
+suggested by Apple's Aqua Style Guildelines. This support is limited to Mac
+OS X >10.1.4, when this version is not detected it will fallback to the old
+text rendering library.
+
+\section1 Library Support
+
+\section2 Bundle-based Libraries
+
+If you want to incorporate dynamic libraries as part of your Mac OS X
+application bundle (the application directory), then you place these into a
+directory called Frameworks, a subdirectory of the application bundle.
+
+The application finds these dynamic libraries if the libraries have an
+install name of "@executable_path/../Frameworks/libname.dylib.
+
+If you use qmake and Makefiles, use the QMAKE_LFFLAGS_SONAME setting:
+
+\code
+QMAKE_LFLAGS_SONAME  = -Wl,-install_name,@executable_path/../Frameworks/
+\endcode
+
+In case of Project Builder, you set the Library targets to have their
+install path (in the Build Settings of the target) set to
+"@executable_path/.../Frameworks". You also need to add a custom build
+setting called "SKIP_INSTALL" and set this to YES. In the Application
+target you need to add a Copy Files build phase that will copy the library
+product into the applications wrapper's Framework sub-folder.
+
+Note that DYLD_LIBRARY_PATH environment variables will override these
+settings, same with any other default paths such as a lookup of dynamic
+libraries inside /usr/lib and similar default locations.
+
+We still strongly recommend to build static applications where the library
+code is incorporated into the Mac OS X binary. However, in case you ship
+applications that retquire plugin support,then you need to use dynamic
+libraries as part of your application.
+
+
+\section2 Combining Libraries
+
+If you want to build a new dynamic library combining the Qt 3.1 dynamic
+libraries, you need to introduce the ld -r flag so that relocation information
+is stored in the the output file, so that this file could be the subject of 
+another ld run. This is done by setting the -r flag in the .pro file, and the
+LFLAGS settings.
+
+\section2 Initialization Order
+
+dyld(1) will call global static initializers in the order in which
+they are linked into your application. If a library links against Qt
+and references globals in Qt (from global initializers in your own
+library) you should be sure to link against Qt before your library,
+otherwise the result will be undefined (as Qt's global initializers
+have not been called yet).
+
+\section2 Plugin Support
+
+Note that it is not possible to build Qt plugins using Project Builder
+or Xcode. Use \link qmake-manual.book qmake\endlink to configure and
+build plugins.
+
+\section1 Compiler Settings
+
+\section2 Compile-time Flags
+
+If you want to wrap any specific Mac OS X code in a define, use the Q_OS_MACX
+flag, as in:
+
+\code
+#if defined(Q_OS_MACX)
+// the code used
+#endif
+\endcode
+
+Note that when you build under Mac OS X 10.2, then the MACOSX_102 flag is
+automatically included in the make builds.
+
+
+\section1 Building and Configuring Qt/Mac
+
+\section2 Problems building a static configuration
+
+If a static build fails with the following error messages during the
+designer make phase:
+
+\code
+QWidget::sizeHint() const referenced from libtqui expected to be defined in @executable_path/../Frameworks/libtqt-mt.3.dylib
+non-virtual thunk [nv:-40] to QWidget::metric(int) const referenced from libtqui
+ expected to be defined in @executable_path/../Frameworks/libtqt-mt.3.dylib
+\endcode
+
+then ensure that your library path does not have libtqui libraries or
+symbolic links. If you remove these, then the build will continue.
+
+
+\section1 Macintosh Native API Access
+
+\section2 Accessing the Bundle Path
+
+The Macintosh application is actually a directory (ending with .app). This
+directory has various other sub-directories and sources. In case you want
+to place for example the plugin directory inside this bundle, then you need
+to find out where the bundle resides on the disk. The following code will
+do this:
+
+\code
+        CFURLRef pluginRef = CFBundleCopyBundleURL(CFBundleGetMainBundle());
+        CFStringRef macPath = CFURLCopyFileSystemPath(pluginRef, 
+                                               kCFURLPOSIXPathStyle);
+        const char *pathPtr = CFStringGetCStringPtr(macPath, 
+                                               CFStringGetSystemEncoding());
+        qDebug("Path = %s", pathPtr);
+        CFRelease(pluginRef);
+        CFRelease(macPath);
+\endcode
+
+Do not forget to enclosure this in an #if defined(Q_OS_MACX) macro statement.
+
+\section2 Translating the Application Menu and native dialogs
+
+You need to do a little extra to get the Application Menu and native dialogs
+localized. This is a retquirement of Mac OS X and not of Qt.
+
+First, you must add a localized resource folder inside the Bundle see:
+
+http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html
+
+And look for the heading: Adding Localized Resources
+
+The main thing you need to do is create a file called locversion.plist.
+Here is an example one for Norwegian:
+
+\code
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
+"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+        <key>LprojCompatibleVersion</key>
+        <string>123</string>
+        <key>LprojLocale</key>
+        <string>no</string>
+        <key>LprojRevisionLevel</key>
+        <string>1</string>
+        <key>LprojVersion</key>
+        <string>123</string>
+</dict>
+</plist>
+\endcode
+
+Then when you run the application with your preferred language set to Norwegian
+you should see menu items like "Avslutt" instead of "Quit"
+
+\section1 User Interface
+
+\section2 Right-Mouse Clicks
+
+If you want to provide right-mouse click support for Mac OS X, use the
+QContextMenuEvent class. This will map to a context menu event, in other
+words a menu that will display a popup selection. This is the most common
+use of right-mouse clicks, and maps to a control-click with the Mac OS X
+one-button mouse support.
+
+\section2 Menubar
+
+Qt/Mac will automatically detect your menubars for you and turn them
+into Mac native menubars. Fitting this into your existing Qt application
+will normally be automatic, however, if you have special needs the Qt/Mac
+implementation currently selects a menubar by starting at the active window
+(ie QApplication::activeWindow()), and applying:
+
+1) If the window has a QMenuBar then it is used.
+2) If the window is a modal then its menubar is used. If no menubar is
+   specified then a default menubar is used (as documented below)
+3) If the window has no parent then the default menubar is used (as documented below).
+
+The above 3 steps are applied all the way up the parent window chain until
+one of the above are satisifed. If all else fails a default menubar will be
+created, the default menubar on Qt/Mac is an empty menubar, however you can
+create a different default menubar by creating a parentless QMenuBar, the
+first one created will thus be designated the default menubar, and will be
+used whenever a default menubar is needed.
+
+\section1 Limitations
+
+\section2 MenuItems
+
+\list
+
+\i QCustomMenuItems are not supported in Mac native menubars, they are supported
+in popupmenus that are not in the Mac native menubar.
+
+\i Items with accelerators that have more than one keystroke
+(QKeySequence) will not be honored, and the first key will be used.
+
+\endlist
+
+\section2 Unsupported Native Widgets
+
+Qt/Mac 3.x has no support for sheets or drawers. Support for these types of windows is provided in Qt/Mac 4.x.
+*/