From eb8c2574848da1a418dbcec6f43699b2a2bc7edc Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Thu, 30 Jul 2009 14:47:14 +0200 Subject: Doc: Move class and function documentation into a dedicated directory. --- doc/src/classes/phonon-api.qdoc | 5023 +++++++++++++++++++++++++++++++++ doc/src/classes/q3asciicache.qdoc | 465 +++ doc/src/classes/q3asciidict.qdoc | 416 +++ doc/src/classes/q3cache.qdoc | 461 +++ doc/src/classes/q3dict.qdoc | 446 +++ doc/src/classes/q3intcache.qdoc | 446 +++ doc/src/classes/q3intdict.qdoc | 390 +++ doc/src/classes/q3memarray.qdoc | 523 ++++ doc/src/classes/q3popupmenu.qdoc | 76 + doc/src/classes/q3ptrdict.qdoc | 388 +++ doc/src/classes/q3ptrlist.qdoc | 1157 ++++++++ doc/src/classes/q3ptrqueue.qdoc | 230 ++ doc/src/classes/q3ptrstack.qdoc | 217 ++ doc/src/classes/q3ptrvector.qdoc | 427 +++ doc/src/classes/q3sqlfieldinfo.qdoc | 234 ++ doc/src/classes/q3sqlrecordinfo.qdoc | 89 + doc/src/classes/q3valuelist.qdoc | 569 ++++ doc/src/classes/q3valuestack.qdoc | 149 + doc/src/classes/q3valuevector.qdoc | 274 ++ doc/src/classes/qalgorithms.qdoc | 651 +++++ doc/src/classes/qcache.qdoc | 244 ++ doc/src/classes/qcolormap.qdoc | 152 + doc/src/classes/qdesktopwidget.qdoc | 266 ++ doc/src/classes/qiterator.qdoc | 1431 ++++++++++ doc/src/classes/qmacstyle.qdoc | 261 ++ doc/src/classes/qpagesetupdialog.qdoc | 84 + doc/src/classes/qpaintdevice.qdoc | 289 ++ doc/src/classes/qpair.qdoc | 229 ++ doc/src/classes/qpatternistdummy.cpp | 1010 +++++++ doc/src/classes/qplugin.qdoc | 135 + doc/src/classes/qprintdialog.qdoc | 72 + doc/src/classes/qprinterinfo.qdoc | 137 + doc/src/classes/qset.qdoc | 953 +++++++ doc/src/classes/qsignalspy.qdoc | 98 + doc/src/classes/qsizepolicy.qdoc | 522 ++++ doc/src/classes/qtdesigner-api.qdoc | 1413 ++++++++++ doc/src/classes/qtendian.qdoc | 168 ++ doc/src/classes/qtestevent.qdoc | 191 ++ doc/src/classes/qvarlengtharray.qdoc | 274 ++ doc/src/classes/qwaitcondition.qdoc | 188 ++ doc/src/phonon-api.qdoc | 5023 --------------------------------- doc/src/q3asciicache.qdoc | 465 --- doc/src/q3asciidict.qdoc | 416 --- doc/src/q3cache.qdoc | 461 --- doc/src/q3dict.qdoc | 446 --- doc/src/q3intcache.qdoc | 446 --- doc/src/q3intdict.qdoc | 390 --- doc/src/q3memarray.qdoc | 523 ---- doc/src/q3popupmenu.qdoc | 76 - doc/src/q3ptrdict.qdoc | 388 --- doc/src/q3ptrlist.qdoc | 1157 -------- doc/src/q3ptrqueue.qdoc | 230 -- doc/src/q3ptrstack.qdoc | 217 -- doc/src/q3ptrvector.qdoc | 427 --- doc/src/q3sqlfieldinfo.qdoc | 234 -- doc/src/q3sqlrecordinfo.qdoc | 89 - doc/src/q3valuelist.qdoc | 569 ---- doc/src/q3valuestack.qdoc | 149 - doc/src/q3valuevector.qdoc | 274 -- doc/src/qalgorithms.qdoc | 651 ----- doc/src/qcache.qdoc | 244 -- doc/src/qcolormap.qdoc | 152 - doc/src/qdesktopwidget.qdoc | 266 -- doc/src/qiterator.qdoc | 1431 ---------- doc/src/qpagesetupdialog.qdoc | 84 - doc/src/qpaintdevice.qdoc | 289 -- doc/src/qpair.qdoc | 229 -- doc/src/qpatternistdummy.cpp | 1010 ------- doc/src/qplugin.qdoc | 135 - doc/src/qprintdialog.qdoc | 72 - doc/src/qprinterinfo.qdoc | 137 - doc/src/qset.qdoc | 953 ------- doc/src/qsignalspy.qdoc | 98 - doc/src/qsizepolicy.qdoc | 522 ---- doc/src/qstyles.qdoc | 261 -- doc/src/qtdesigner.qdoc | 1373 --------- doc/src/qtendian.qdoc | 168 -- doc/src/qtestevent.qdoc | 191 -- doc/src/qvarlengtharray.qdoc | 274 -- doc/src/qwaitcondition.qdoc | 188 -- 80 files changed, 20748 insertions(+), 20708 deletions(-) create mode 100644 doc/src/classes/phonon-api.qdoc create mode 100644 doc/src/classes/q3asciicache.qdoc create mode 100644 doc/src/classes/q3asciidict.qdoc create mode 100644 doc/src/classes/q3cache.qdoc create mode 100644 doc/src/classes/q3dict.qdoc create mode 100644 doc/src/classes/q3intcache.qdoc create mode 100644 doc/src/classes/q3intdict.qdoc create mode 100644 doc/src/classes/q3memarray.qdoc create mode 100644 doc/src/classes/q3popupmenu.qdoc create mode 100644 doc/src/classes/q3ptrdict.qdoc create mode 100644 doc/src/classes/q3ptrlist.qdoc create mode 100644 doc/src/classes/q3ptrqueue.qdoc create mode 100644 doc/src/classes/q3ptrstack.qdoc create mode 100644 doc/src/classes/q3ptrvector.qdoc create mode 100644 doc/src/classes/q3sqlfieldinfo.qdoc create mode 100644 doc/src/classes/q3sqlrecordinfo.qdoc create mode 100644 doc/src/classes/q3valuelist.qdoc create mode 100644 doc/src/classes/q3valuestack.qdoc create mode 100644 doc/src/classes/q3valuevector.qdoc create mode 100644 doc/src/classes/qalgorithms.qdoc create mode 100644 doc/src/classes/qcache.qdoc create mode 100644 doc/src/classes/qcolormap.qdoc create mode 100644 doc/src/classes/qdesktopwidget.qdoc create mode 100644 doc/src/classes/qiterator.qdoc create mode 100644 doc/src/classes/qmacstyle.qdoc create mode 100644 doc/src/classes/qpagesetupdialog.qdoc create mode 100644 doc/src/classes/qpaintdevice.qdoc create mode 100644 doc/src/classes/qpair.qdoc create mode 100644 doc/src/classes/qpatternistdummy.cpp create mode 100644 doc/src/classes/qplugin.qdoc create mode 100644 doc/src/classes/qprintdialog.qdoc create mode 100644 doc/src/classes/qprinterinfo.qdoc create mode 100644 doc/src/classes/qset.qdoc create mode 100644 doc/src/classes/qsignalspy.qdoc create mode 100644 doc/src/classes/qsizepolicy.qdoc create mode 100644 doc/src/classes/qtdesigner-api.qdoc create mode 100644 doc/src/classes/qtendian.qdoc create mode 100644 doc/src/classes/qtestevent.qdoc create mode 100644 doc/src/classes/qvarlengtharray.qdoc create mode 100644 doc/src/classes/qwaitcondition.qdoc delete mode 100644 doc/src/phonon-api.qdoc delete mode 100644 doc/src/q3asciicache.qdoc delete mode 100644 doc/src/q3asciidict.qdoc delete mode 100644 doc/src/q3cache.qdoc delete mode 100644 doc/src/q3dict.qdoc delete mode 100644 doc/src/q3intcache.qdoc delete mode 100644 doc/src/q3intdict.qdoc delete mode 100644 doc/src/q3memarray.qdoc delete mode 100644 doc/src/q3popupmenu.qdoc delete mode 100644 doc/src/q3ptrdict.qdoc delete mode 100644 doc/src/q3ptrlist.qdoc delete mode 100644 doc/src/q3ptrqueue.qdoc delete mode 100644 doc/src/q3ptrstack.qdoc delete mode 100644 doc/src/q3ptrvector.qdoc delete mode 100644 doc/src/q3sqlfieldinfo.qdoc delete mode 100644 doc/src/q3sqlrecordinfo.qdoc delete mode 100644 doc/src/q3valuelist.qdoc delete mode 100644 doc/src/q3valuestack.qdoc delete mode 100644 doc/src/q3valuevector.qdoc delete mode 100644 doc/src/qalgorithms.qdoc delete mode 100644 doc/src/qcache.qdoc delete mode 100644 doc/src/qcolormap.qdoc delete mode 100644 doc/src/qdesktopwidget.qdoc delete mode 100644 doc/src/qiterator.qdoc delete mode 100644 doc/src/qpagesetupdialog.qdoc delete mode 100644 doc/src/qpaintdevice.qdoc delete mode 100644 doc/src/qpair.qdoc delete mode 100644 doc/src/qpatternistdummy.cpp delete mode 100644 doc/src/qplugin.qdoc delete mode 100644 doc/src/qprintdialog.qdoc delete mode 100644 doc/src/qprinterinfo.qdoc delete mode 100644 doc/src/qset.qdoc delete mode 100644 doc/src/qsignalspy.qdoc delete mode 100644 doc/src/qsizepolicy.qdoc delete mode 100644 doc/src/qstyles.qdoc delete mode 100644 doc/src/qtendian.qdoc delete mode 100644 doc/src/qtestevent.qdoc delete mode 100644 doc/src/qvarlengtharray.qdoc delete mode 100644 doc/src/qwaitcondition.qdoc diff --git a/doc/src/classes/phonon-api.qdoc b/doc/src/classes/phonon-api.qdoc new file mode 100644 index 0000000..09274bf --- /dev/null +++ b/doc/src/classes/phonon-api.qdoc @@ -0,0 +1,5023 @@ +/* + This file is part of the KDE project + Copyright (C) 2005-2007 Matthias Kretz + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Nokia Corporation (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library 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 + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + + +/*! + \enum Phonon::DiscType + Enum to identify the media discs supported by MediaObject. + + \value NoDisc + No disc was selected. This is only useful as a return value from + MediaSource::diskType(). + \value Cd Identifies Audio CDs. + \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). + \value Vcd Identifies Video CDs. + + \sa MediaSource, MediaObject +*/ + +/*! + \enum Phonon::MetaData + + Provided as keys for Phonon::MediaObject::metaData(). The enum + values matches strings defined in the Ogg Vorbis specification + + \value ArtistMetaData + \value AlbumMetaData + \value TitleMetaData + \value DateMetaData + \value GenreMetaData + \value TracknumberMetaData + \value DescriptionMetaData + \value MusicBrainzDiscIdMetaData +*/ + +/*! + \enum Phonon::State + \since 4.4 + + The state enum describes the different states a media object can + take. Several functions of \l{Phonon::}{MediaObject} are + asynchronous, so even if a you have requested a state change + through a function call, e.g., through + \l{Phonon::MediaObject::}{play()}, you cannot be sure that the + change has taken place before you receive the + \l{Phonon::MediaObject::}{stateChanged()} signal. + + A media object can at any time change into any state, regardless + of the state it previously had. \omit In the + \l{Phonon::}{MediaObject} class description explains the typical + state changes in the life of a media object. \endomit + + \value LoadingState + After construction it might take a while before the media object + is ready to \l{Phonon::MediaObject::}{play()}. This state is + commonly used by backends to initialize the \l{Phonon + Overview}{media graph} and loading the source. When + the object leaves the loading state, it will enter the + StoppedState unless an error occurred or another state is + requested through a function call, e.g., + \l{Phonon::}{MediaObject::play()}. + + \value StoppedState + In the stopped state, the media object is ready to play its + current media source. The current + \l{MediaObject::seek()}{position} in the media stream is then 0. + + \value PlayingState + The media object is playing back its media source. + + \value BufferingState + The Player is waiting for data to be able to start or continue + playing. This state is commonly used to wait for media data over a + network connection. + + \value PausedState + The media player has currently paused its playback, i.e., it + stops playing but keeps the current playback position in the + stream. + + \value ErrorState + When a media object enters the error state a problem with the + playback has occurred. The possible errors are grouped into + two categories by Phonon::ErrorType, and the type can be + queried through \l{Phonon::MediaObject::}{errorType()}. A + \l{Phonon::}{FatalError} implies that the playback + cannot continue, but one can still try with a new media + source. With a \l{Phonon::}{NormalError} it might + be possible to continue playback, and a media object may + therefore change state from the ErrorState. + + \sa MediaObject +*/ + +/*! + \enum Phonon::Category + + Sets the category your program should be listed in in the mixer. + + \value NoCategory + Will make use of the default device. + \value NotificationCategory + If the sounds produced are notifications (ping, beep and such) you + should use this category. + \value MusicCategory + If your application is a music player (like a jukebox or media player + playing an audio file). + \value VideoCategory + If the sound is the audio channel of a video. + \value CommunicationCategory + If your applications produces sounds from communication with somebody + else (VoIP, voice chat). + \value GameCategory + Sound produced by a computer game should go into this category. + \value AccessibilityCategory + Sounds produced for accessibility (e.g., Text-To-Speech) + \omitvalue LastCategory + Holds the largest value of categories. + \omitvalue AccessibilityCategory + + A Jukebox will set this to Music, a VoIP program to Communication, a + DVD player to video, and so on. + + \note These categories can also become useful for an application that + controls the volumes automatically, like turning down the music when a call + comes in, or turning down the notifications when the media player knows + it's playing classical music. +*/ + +/*! + \enum Phonon::ErrorType + + This enum describes the severity when an error has occurred during + playback. + + After a media object has entered the \l{Phonon::}{ErrorState}, one + can query the type of error from + \l{Phonon::}{MediaObject::errorType()}. Note that you should query + the error when receiving the + \l{Phonon::}{MediaObject::stateChanged()} signal, because the + error type will be lost if the media object leaves the error + state. + + \value NoError No error. MediaObject::errorType() returns this if + MediaObject::state() != Phonon::ErrorState. + + \value NormalError An error has occurred with the playback of the current + source. It might be possible to continue playback, for instance, if only the + audio stream in a video cannot be played back. The media object will then + leave the error state again. + + \value FatalError. Something important does not work. Your program cannot continue + the playback of the current source, but it might be possible to try another. + + \sa MediaObject::errorType() +*/ + +/*! + \fn QString Phonon::categoryToString(Category c) + + Returns a (translated) string to show to the user identifying the given + Category (\a c). +*/ + +/*! + \enum Phonon::ObjectDescriptionType + \relates Phonon::ObjectDescription + + This enum defines the type of information that is contained in a + \l{Phonon::}{ObjectDescription} object. + + \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). + This can be soundcards (with different drivers), + sound servers, or other virtual outputs like playback on a different + computer on the network. + + \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). + \omitvalue SubtitleType + \omitvalue AudioCaptureDeviceType + \omitvalue AudioChannelType +*/ + +/*! + \typedef Phonon::AudioOutputDevice + \relates Phonon::ObjectDescription + + This typedef of \l{Phonon::}{ObjectDescription} describes an audio output + device, such as soundcards (with different drivers), sound servers, or other + virtual outputs like playback on a different computer on the network. + + \omit + For Hardware devices the backend should use libkaudiodevicelist + (AudioDevice and AudioDeviceEnumerator) which will list removable + devices even when they are unplugged and provide a unique identifier + that can make backends use the same identifiers. + \endomit + + A list of available devices is given by the backend with + Backendcapabilities::availableAudioOutputDevices() + + \snippet doc/src/snippets/phononobjectdescription.cpp 1 + +*/ + +/*! + \fn Phonon::phononVersion() + \inmodule Phonon + \since 4.5 + + Returns the Phonon version. +*/ + +/*! + \class Phonon::ObjectDescription + \inmodule Phonon + \inheaderfile Phonon/ObjectDescription + \since 4.4 + \brief The ObjectDescription class provides information about Phonon objects. + + Phonon currently uses this class to describe audio effects and + audio output devices - using the typedefs AudioOutputDevice and + EffectDescription. The type of an ObjectDescription is also + described through the \l{Phonon::}{ObjectDescriptionType} enum. + Objects of the same \l{Phonon::ObjectDescriptionType}{type} are + uniquely identified by an index(). + + The class gives a description() and a name() of the object, both + of which are strings appropriate for end users of a Phonon + application. You can also check whether the device or effect + described is \l{isValid()}{valid}. This does not guarantee that + the device or effect functions as expected, but that the + ObjectDescription describes an existing device or effect. + + Audio output devices and effect descriptions are used to select + the audio output device to be used for playback and to create + effects; we show examples of this in the snippet below. The + available descriptions can be fetched with + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} + and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} + static functions in the Phonon::BackendCapabilities namespace + + \snippet doc/src/snippets/phononobjectdescription.cpp 0 + + Other types of ObjectDescriptions might be possible in the future, + e.g., descriptions of audio capture devices, such as microphones. + + \omit Not implemented yet. + Need a new paragraph on that some descriptions 'belong + together', such as chained audio effects. + + Some parts give the end user choices, e.g. what source to capture + audio from. These choices are described by the name and + description methods of this class and identified with the id + method. Subclasses then define additional information like which + audio and video choices belong together. \endomit + + \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription() + \brief constructs a new object description. + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash & properties) + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer &dd) + \internal +*/ + +/*! + \fn static inline ObjectDescription Phonon::ObjectDescription::fromIndex(int index) + \internal + + \omit Currently indices are not unique for all ObjectDescription types, making + the behavior of this function undefined. \endomit + + Returns a new description object that describes the + device/effect/codec/... with the given \a index. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + object as \a otherDescription; otherwise, returns \c false. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const + Returns \c false if this ObjectDescription describes the same + as \a otherDescription; otherwise, returns \c true. +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::name() const + + Returns a string appropriate for a user to select between + object descriptions, e.g., from a QComboBox. + + \sa description() +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::description() const + + Returns a more extensive description than the name() function. + + For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this + text should make clear which sound source is described; this is + sometimes hard to describe or understand from just the name. + + The text is appropriate to present to an end user in for example + tool tips of items, with the name()'s as text, in a QComboBox. + +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const + + Returns the property named \a name. A property can be used for + extended information, such as the manufacturer of a sound card. The + information will usually be given as text. + + If the property is not set an invalid QVariant is returned. + + Qt's backends do not use properties at the time of this writing. + + \sa propertyNames() +*/ + +/*! + \fn inline QList Phonon::ObjectDescription::propertyNames() const + + Properties can be used for extended information about a + ObjectDescription, e.g., a manufacturer of a sound card. The + information will usually be given text. + + This function returns all names that return valid data when + property() is called. + + Currently, Qt backends do not use properties for their object + descriptions. + + \sa property() +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::isValid() const + + Returns true if the device or effect described exists. + + An ObjectDescription that is invalid, will also have an + index() of -1. + + \sa index() +*/ + +/*! + \fn inline int Phonon::ObjectDescription::index() const + + Returns a unique identifier for this ObjectDescription. Used + internally to distinguish between the descriptions. + + Notice that the identifiers are only unique to the type of + description, e.g., \l{Phonon::}{AudioOutputDevice} or + \l{Phonon::}{EffectDescription}. +*/ + +/*! + \class Phonon::ObjectDescriptionPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::StreamInterface + \inmodule Phonon + \since 4.4 + \brief Backend interface to handle media streams (AbstractMediaStream). + \internal +*/ + +/*! + \fn virtual Phonon::StreamInterface::~StreamInterface() +*/ + +/*! + \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::endOfData() = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::needData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::enoughData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::seekStream(qint64) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::reset() + \internal +*/ + +/*! + \fn Phonon::StreamInterface::StreamInterface() + \internal + \omit + For subclasses. + \endomit +*/ + +/*! + \class StreamInterfacePrivate + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AbstractVideoOutput + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractVideoOutput class is the common base class for all video output classes. + + \sa VideoWidget +*/ + +/*! + \namespace Phonon::Experimental + \internal +*/ + +/*! + \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) + \internal + + Constructor that is called from derived classes. + + \param parent Standard QObject parent. +*/ + +/*! + \class Phonon::AbstractVideoOutputPrivate + \inmodule Phonon + \internal + \since 4.4 +*/ + +/*! + \class Phonon::VolumeFaderEffect + \inmodule Phonon + \internal + \since 4.4 + + This effect differs from gradually changing the output volume in that + a dedicated effect can change the volume in the smallest possible + steps while every other volume control will make more or less + noticeable steps. + + \sa AudioOutput::volume() +*/ + +/*! + \property Phonon::VolumeFaderEffect::volume + + This is the current volume of the output as voltage factor. + Setting this property changes the volume immediately. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% + + \sa volumeDecibel +*/ + +/*! + \property Phonon::VolumeFaderEffect::volumeDecibel + + This is the current volume of the output in decibel. + Setting this property changes the volume immediately. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::VolumeFaderEffect::fadeCurve + + This property holds the fade curve to be used for the fadeIn(), fadeOut() + and fadeTo() slots. + + Defaults to Fade3Decibel. + + \sa FadeCurve +*/ + +/*! + \enum Phonon::VolumeFaderEffect::FadeCurve + Determines the curve of the volume change. + + \value Fade3Decibel Crossfade curve/fast fade out. + This is the default fade curve. + \value Fade6Decibel Linear fade out. + \value Fade9Decibel Slow fade out. + \value Fade12Decibel A more extreme version of the -9dB fade. + + \bold{Notes:} + + \c Fade3Decibel is often the best fade for a crossfade, as after half + of the time the volume reached -3dB. This means that half the + possible power (which is proportional to the square of the + voltage) is reached. Summed, the maximum power of two audio + signals fading with a -3dB curve will always be equal. + + For fading in or out the -3dB curve is too abrupt in the end. + + With a -6dB fade curve, a volume of -6dB is reached after half of + the fading time. -6dB is equal to half of the voltage meaning + that the voltage multiplier changes linearly from the start + of the fade to the end. + + With the \c Fade9Decibel fade, a volume of -9dB is reached after + half of the fade time, so the fade is fast in the beginning and + slow at the end. This is a good fade for ending music. +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) + + Tells the Fader to change the volume from the current volume to 100% + in \a fadeTime milliseconds. + + Short for \c fadeTo(1.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo(), volume +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) + + Tells the Fader to change the volume from the current volume to 0% + in \a fadeTime milliseconds. + Short for \c fadeTo(0.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) + + Tells the Fader to change the volume from the current value to + \a volume in \a fadeTime milliseconds. + + \sa fadeIn(), fadeOut() +*/ + +/*! + \class Phonon::VolumeFaderEffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::VolumeFaderInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() + \internal +*/ + +/*! + \fn virtual float Phonon::VolumeFaderInterface::volume() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) + \internal +*/ + +/*! + \class Phonon::AbstractMediaStream + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractMediaStream class is the base class for custom media data streams. + \inheaderfile Phonon/AbstractMediaStream + + This class is subclassed to provide custom data streams for + \l{Phonon::}{MediaSource}s. + + The \l{Phonon::}{MediaSource} knows how to handle the most common + media sources, such as files and CD. If you need to fetch + multimedia from other sources, you can reimplement this class, + which can be used by a \l{Phonon::}{MediaSource}. + + When a backend needs more data from the stream, needData() will be + called. You must then use writeData() to write the data to the + backend. You can either write one time and wait for a new + needData() call, or continue to write data until you receive an + enoughData() call. When the stream is at its end, call endOfData() + instead of writeData(). + + Before the custom stream is passed to a \l{Phonon::}{MediaSource}, + setStreamSize() needs to be called, and also setStreamSeekable() + (if the stream is seekable). A good place to do this work is in + the constructor. A seekable stream must also reimplement + seekStream(). + + We show two examples. The first writes data repeatedly until it + receives the enoughData() call, while the second only writes once + and waits for a new needData() call. + + Example where data is written repeatedly. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 + + Example where data is written once: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 + + \sa Phonon::MediaSource, Phonon::MediaObject + +*/ + +/*! + \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) + \internal + + Constructs an AbstractMediaStream object with the given \a parent. + +*/ + +/*! + \fn qint64 Phonon::AbstractMediaStream::streamSize() const + + Returns the stream size that was set with setStreamSize(). + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + \sa setStreamSize() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) + + Sets the \a size of the stream in number of bytes. + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + This function has to be called. A backend will not call needData() + until the stream size is set. + + \sa streamSize() + +*/ + +/*! + \fn bool Phonon::AbstractMediaStream::streamSeekable() const + + Returns whether your data stream is set as seekable. + + Defaults to \c false. + + \sa setStreamSeekable() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) + + Sets whether your data stream is seekable. \a s should be true if + the stream is seekable; otherwise false. + + Defaults to \c false. + + If you set this to \c true you have to implement the seekStream() + function. + + \sa streamSeekable() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) + + Sends the media \a data to the backend for decoding. + + Use this function to send data to the backend after needData() has + been called. + + If your stream is a push stream, data should be written until the + enoughData() function is called. For a pull stream, write data + once before the call to needData() function returns. + + If the data is depleted, call endOfData() instead of writeData(). + + \warning Don't call this function before the first needData() is emitted. + + \sa needData(), endOfData() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::endOfData() + + Tells the backend that the media data stream is at its end. + + \warning Don't call this function before the first needData() is emitted. + + \sa writeData(), needData() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) + + If an I/O error occurs you should call this function to make + MediaObject go into ErrorState. \c errorType classifies the error, + while \a errorString is a textual description of the error suitable + for users of Phonon applications. + + \sa MediaObject::errorType(), MediaObject::errorString() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::reset() = 0 + + Reimplement this function to reset the stream. Subsequent calls to writeData should start + from the first position of the data unless a seek is requested. + + The function is necessary for the case where a non-seekable MediaStream is + played more than once. For a seekable stream the implementation can simply call + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 + + \sa writeData(), needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::needData() = 0 + + Reimplement this function to be notified when the backend needs data. + + When this function is called you should write data to the backend + (See writeData()). + + \sa writeData(), endOfData(), enoughData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::enoughData() + + If your stream is a push stream, reimplement this function to be + notified when the backend has enough data and your stream object + may take a break. + + This method is important for pushing data to the backend in order + to not fill the backend buffer unnecessarily. + + \sa needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) + + Reimplement this function if your stream is seekable. + + When this function is called the next call to writeData has to be at the + requested \a offset. + + \warning Do not call the parent implementation. + + \sa setStreamSeekable(), streamSeekable(), needData() +*/ + +/*! + \class Phonon::BackendInterface + \inmodule Phonon + \since 4.4 + \brief Main Backend class interface + \internal + + This interface defines the main factory of the backend. The createObject() function creates all the + objects needed by the frontend. + + The objectDescriptionIndexes and objectDescriptionProperties functions return information about + available devices, effects and codecs. + + An implementation could look like this: + \snippet snippets/phonon/samplebackend/main.cpp snippet + +*/ + +/*! + \fn virtual Phonon::BackendInterface::~BackendInterface() + \internal + + Silence gcc's warning. +*/ + +/*! + \enum Phonon::BackendInterface::Class + \internal + + Classes that the createObject() function has to handle. + + \value MediaObjectClass Request to return a \c MediaObject object. + \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect + object. + \value AudioOutputClass Request to return an \c AudioOutput object. + \value AudioDataOutputClass Request to return an \c AudioDataOutput object. + \value VisualizationClass Request to return a \c Visualization object. + \value VideoDataOutputClass Request to return a \c VideoDataOutput object. + \value EffectClass Request to return a \c Effect object. + Takes an additional int that specifies the effect ID. + \value VideoWidgetClass Request to return a \c VideoWidget object. +*/ + +/*! + \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList &args = QList()) = 0 + \internal + + Returns a new instance of the requested class. + + \param c The requested class. + \param parent The parent object. + \param args Additional arguments (documented in Class). +*/ + + +/*! + \fn virtual QList Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 + \internal + + Returns the unique identifiers for the devices/effects/codecs of the given \a type. + + \param type see ObjectDescriptionType +*/ + +/*! + \fn virtual QHash Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 + \internal + + Given a unique identifier that was returned from objectDescriptionIndexes this function + returns a hash mapping property names to values. + + The property "name" must always be present. All other properties are optional. + + \table + \header \o Property \o Description + \row \o name \o The name of the device/effect/codec/... + \row \o description \o A text explaining what this device/effect/codec/... is/can do + \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this + device/effect/codec/... + \row \o available \o A bool telling whether the device is present or unplugged. + \endtable + + \param type see ObjectDescriptionType + \param index The unique identifier that is returned from objectDescriptionIndexes +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet) = 0; + \internal + + When this function is called the nodes given in the parameter list should + not lose any signal data when connections are changed. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 + \internal + + Defines a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 + \internal + + Cuts a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet) = 0 + \internal + + When this function is called the nodes given in the parameter list may lose + signal data when a port is not connected. +*/ + +/*! + \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 + \internal + + Returns all available MIME types. +*/ + +/*! + \class Phonon::MediaSource + \inmodule Phonon + \inheaderfile Phonon/MediaSource + \since 4.4 + \brief The MediaSource class provides multimedia data for media objects. + + The MediaSource class manages a source of multimedia content, such + as a music or video file, of which data is given to a + \l{Phonon::}{MediaObject}. + + The media source knows how fetch its data from several sources, + e.g., from files, a QIODevice, or a CD. The possible source types + are described by the \l{MediaSource::}{Type} enum. The type of the + source is set by the media source itself, and is dependent on the + constructor used to create it. Note that it is possible to provide + data from any source by implementing a QIODevice. + + The class has several functions to acquire information about the + source it manages, e.g., fileName() and url(). The return from + these functions are dependent on the type() of the media source. + + Normally, a programmer does not need to be concerned with media + sources. It's constructors are implicit, so one can, for instance, + send an URL or filename directly to the constructors of the + \l{Phonon::}{MediaObject}. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 + + A MediaSource object cannot be reused for another multimedia + source. It is possible to play the same source again, and also + stop and start a non-seekable media source, such as a radio + stream, with the same MediaSource object. + + \section1 Qt Backends + + Currently, Qt's backends support files in local and remote + locations. Support for other sources, such as CD/DVD, are planned + for the future. + + \sa MediaObject, {Phonon Module} +*/ + +/*! + \enum Phonon::MediaSource::Type + + Identifies the type of media described by the MediaSource object. + + \value Invalid The MediaSource object does not describe any valid source. + \value LocalFile The MediaSource object describes a local file. + \value Url The MediaSource object describes an URL, which can be either a + local file or a file on the network. + \value Disc The MediaSource object describes a disc, e.g., a CD. + \value Stream The MediaSource object describes a data stream. + This is the type used for \l{QIODevice}s. Note + that a stream opened with a QUrl, will still be of the Url type. + \value Empty The media source doesn't have a source. + + \sa MediaSource::type() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource() + \internal + + Creates an invalid MediaSource object. + + \sa Invalid +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QString &fileName) + + Creates a MediaSource object for the file specified by \a + fileName. You can also use this constructor with \l{The Qt + Resource System}{Qt resources} + + \omit + \param fileName file name of a local media file or a Qt resource that was compiled in. + \endomit +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QUrl &url) + + Creates a MediaSource object for a the URL specified by \a url. + + If the multimedia content you would like to play back is on a + remote network location, you should use this constructor; though, + it also possible to specify an URL to a local file. + + \sa QUrl +*/ + + +/*! + \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) + + Creates a MediaSource object for the type of disc specified by \a discType in the named + device referred to by \a deviceName. + + \note \a deviceName is a platform dependent device name. It can be useful to specify this + if the computer has more than one CD drive. On KDE, it is recommended to use the Solid + hardware discovery framework to retrieve the device name in a portable way. +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) + \internal + Creates a MediaSource object for a data stream. + + Your application can provide the media data by subclassing AbstractMediaStream and + passing a pointer to that object. Phonon will never delete the \a stream. + + \param stream The AbstractMediaStream subclass to provide the media data. + + \sa setAutoDelete +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) + + Creates a MediaSource object for the QIODevice specified by \a ioDevice. + + This constructor can be very handy in the combination of + QByteArray and QBuffer. + + If you need to fetch multimedia data from a source that is not + supported by MediaSource, you should subclass QIODevice and use + this MediaSource constructor. It is important that you reimplement + QIODevice::isSequential(), as it is used by MediaSource to + determine if the media source is seekable. + + \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened + MediaSource will open it as QIODevice::ReadOnly. + + \note Sequential devices can also be used, but MediaObject::isSeekable() will + return false as a result. + + \warning On Windows, we only support \l{QIODevice}s containing the + \c avi, \c mp3, or \c mpg formats. Use the constructor that takes + a file name to open files (the Qt backend does not use a QFile + internally). + + \sa setAutoDelete() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) + \internal +*/ + +/*! + \fn Phonon::MediaSource::~MediaSource() + + Destroys the MediaSource object. You should never delete a + MediaSource yourself, the MediaObject will handle this. + +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const MediaSource &other) + + Constructs a copy of the \a other media source. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) + + Assigns the \a other media source to this media source and returns a + reference to it. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const + + Returns true if this media source is equal to the \a other media source; + otherwise returns false. +*/ + +/*! + \fn void Phonon::MediaSource::setAutoDelete(bool enable) + + If \a enable is true, the media source will take ownership of the + object passed in the \l{Phonon::}{MediaSource}'s constructor + object that was passed in the constructor; otherwise, the + programmer is responsible for deletion of this object. + + This setting is false by default. If you enable it, you should + only access the stream or device as long as you keep the media + source object around. As long as you keep the media source + wrapping the stream or device, the object will not get deleted. + + \sa autoDelete() +*/ + +/*! + \fn bool Phonon::MediaSource::autoDelete() const + + Returns the setting of the auto-delete option. The default is + false. + + \sa setAutoDelete() +*/ + +/*! + \fn Type Phonon::MediaSource::type() const + + Returns the type of the MediaSource (depends on the constructor + that was used). + + \sa Type +*/ + +/*! + \fn QString Phonon::MediaSource::fileName() const + + Returns the file name of the MediaSource if type() == + LocalFile; otherwise, returns QString(). + + \sa type() +*/ + +/*! + \fn QUrl Phonon::MediaSource::url() const + Returns the URL of the MediaSource if type() == URL or type() == LocalFile; + otherwise returns QUrl(). + + \sa type() +*/ + +/*! + \fn Phonon::DiscType Phonon::MediaSource::discType() const + Returns the disc type of the MediaSource if type() == Disc; otherwise + returns NoDisc. + + \sa type() +*/ + +/*! + \fn QString Phonon::MediaSource::deviceName() const + + Returns the device name of the MediaSource if type() == Disc; otherwise + returns QString(). + + \sa type() +*/ + +/*! + \fn AbstractMediaStream *Phonon::MediaSource::stream() const + \internal + Returns the media stream of the MediaSource if type() == Stream; otherwise + returns 0. + QIODevices are handled as streams, too. +*/ + +/*! + \class Phonon::MediaSourcePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::SeekSlider + \inmodule Phonon + \inheaderfile Phonon/SeekSlider + \since 4.4 + \brief The SeekSlider class provides a slider for seeking to positions in media streams. + + The SeekSlider connects to a \l{Phonon::}{MediaObject}, and + controls the seek position in the object's media stream. + + The slider will connect to the necessary signals to keep track of + the sliders maximum, minimum, and current values. It will also + disable itself for non-seekable streams, and update the media + object when the current value of the slider changes. + + Here follows a typical example of SeekSlider usage: + + \snippet doc/src/snippets/seekslider.cpp 0 + + \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} + +*/ + +/*! + \property Phonon::SeekSlider::iconVisible + \brief whether the icon next to the slider is visible + + By default the icon is visible if the platform provides an icon; else + it's hidden. + +*/ + +/*! + \property Phonon::SeekSlider::tracking + \brief whether slider tracking is enabled + + If tracking is enabled (the default), the media seeks + while the slider is being dragged. If tracking is + disabled, the media seeks only when the user + releases the slider. +*/ + +/*! + \property Phonon::SeekSlider::pageStep + \brief the page step interval + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::singleStep + \brief the single step interval + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 0.5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::orientation + \brief the orientation of the slider + + The orientation must be Qt::Vertical or Qt::Horizontal (the default). +*/ + +/*! + \property Phonon::SeekSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) + + Constructs a seek slider widget with the given \a parent. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) + + Constructs a seek slider widget for the specified \a media with the + given \a parent. +*/ + +/*! + \fn Phonon::SeekSlider::~SeekSlider() + Destroys the seek slider. +*/ + +/*! + \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const + + Return the media object this SeekSlider controls. +*/ + +/*! + \class Phonon::SeekSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) + + Sets the media object to be controlled by this slider to the \a media specified. +*/ + +/*! + \class Phonon::VideoPlayer + \inmodule Phonon + \inheaderfile Phonon/VideoPlayer + \since 4.4 + \brief The VideoPlayer widget is used to perform playback of video. + + With VideoPlayer you can get results quickly and easily. You can + do the standard playback tasks like play(), pause(), and stop(), + but also set a playback volume and seek - if the media and backend + supports seeking. + + VideoPlayer is provided for convenience and removes the need to + create a media graph with a \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If + you need functionality not supported by the player, you can build + this \l{Building Graphs}{graph} yourself. + + Keep in mind that when the VideoPlayer instance is deleted the + playback will stop. + + Note also that most of the functions in this class are + asynchronous. For instance, a media source may not play + immediately after you call the play() function. + + A play and forget code example: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 + + \sa {Phonon Module}, MediaObject +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) + + Constructs a new video widget with a \a parent using + Phonon::VideoCategory as its category. + + \param parent The QObject parent. +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) + + Constructs a new VideoPlayer instance with the specified \a + parent. + + \a category is the category used for the audio output device. +*/ + +/*! + \fn Phonon::VideoPlayer::~VideoPlayer() + + On destruction the playback is stopped, also the audio output is + removed so that the desktop mixer will not show the application + anymore. If you need a persistent audio output don't use + VideoPlayer but MediaObject, VideoPath and VideoOutput. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::currentTime() const + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn float Phonon::VideoPlayer::volume() const + + This is the current volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPlaying() const + + Returns true if it is currently playing; otherwise returns false if it + is currently stopped or paused +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPaused() const + + Returns true if it is currently paused; otherwise returns false if it + is currently playing or stopped. +*/ + +/*! + \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) + + Starts pre-loading the media data from the specified \a source and + filling audio buffers in the backend. + + When there's already a media playing (or paused) it will be stopped + (the finished signal will not be emitted). + + \sa MediaObject::setCurrentSource() +*/ + +/*! + \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) + + Plays the media from the given \a source. Starts playback as fast as + possible. + This can take a considerable time depending on the URL and the + backend. + + If you need low latency between calling play() and the sound actually + starting to play on your output device you need to use MediaObject + and be able to set the URL before calling play(). Note that + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 + doesn't make a difference: the application should be idle between the + load and play calls so that the backend can start preloading the + media and fill audio buffers. +*/ + +/*! + \fn void Phonon::VideoPlayer::play() + + Continues playback of paused media. Restarts playback of a stopped + (or newly loaded) media. + + \sa MediaObject::play(), play() +*/ + +/*! + \fn void Phonon::VideoPlayer::pause() + + Pauses the playback. + + \sa MediaObject::pause() +*/ + +/*! + \fn void Phonon::VideoPlayer::stop() + + Stops the playback. + + \sa MediaObject::stop() +*/ + +/*! + \fn void Phonon::VideoPlayer::seek(qint64 ms) + + Seeks to the requested time. Note that the backend is free to + ignore the seek request if the media source isn't seekable; you + can check this by asking the media object of the VideoPlayer. + + \snippet doc/src/snippets/videomedia.cpp 0 + + The \a ms parameter is the time in milliseconds from the start of + the media. + + The call is asynchronous, so currentTime() can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() +*/ + +/*! + \fn void Phonon::VideoPlayer::setVolume(float volume) + + Sets the \a volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn MediaObject *Phonon::VideoPlayer::mediaObject() const + + Returns the media object being used by the player. + + The media object can be accessed directly instead of using the + \l{VideoPlayer}s convenience functions, e.g., play() and stop(). + It is also possible to give the object to other Phonon widgets, + e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. + + \sa Phonon::SeekSlider, Phonon::MediaObject +*/ + +/*! + \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const + + Returns the audio output object being used by the player. + +*/ + +/*! + \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const + + Returns the video widget being used by the player. +*/ + +/*! + \fn void Phonon::VideoPlayer::finished() + + This signal is emitted when the playback finished. + +*/ + +/*! + \class Phonon::VideoWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObject + \inmodule Phonon + \inheaderfile Phonon/MediaObject + \since 4.4 + \brief The MediaObject class provides an interface for media playback. + + + The media object manages a \l{Phonon::}{MediaSource}, which + supplies the media object with multimedia content, e.g., from a + file. A playback in Phonon is always started by calling the + \l{Phonon::MediaObject::}{play()} function. + + The state of play (play, pause, stop, seek) is controlled by the + media object, and you can also query the current + \l{Phonon::MediaObject::}{state()}. It keeps track of the playback + position in the media stream, and emits the + \l{Phonon::MediaObject::}{tick()} signal when the current position + in the stream changes. + + Notice that most functions of this class are asynchronous, so you + cannot rely on that a state is entered after a function call + before you receive the \l{Phonon::MediaObject::}{stateChanged()} + signal. The description of the \l{Phonon::}{State} enum gives a + description of the different states. + + Before play() is called, the media object should be connected to + \l{Sinks}{output nodes}, which outputs the media to the + underlying hardware. The output nodes required are dependent on + the contents of the multimedia file that is played back. Phonon + has currently two output nodes: the \l{Phonon::}{AudioOutput} for + audio content and \l{Phonon::}{VideoWidget} for video content. If + a \l{Phonon::}{MediaSource} contains both audio and video, both + nodes need to be connected to the media object. + + \snippet snippets/phonon.cpp 4 + \snippet snippets/phonon.cpp 5 + + The media object can queue sources for playback. When it has + finished to play one source, it will start playing the next in the + queue; the new source is then removed from the queue. The + queue can be altered at any time. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 + + You can also make use of the + \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is + guaranteed to be emitted in time for altering the queue. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 + + When playback is finishing, i.e., when a media source has been + played to the end and the queue is empty, several signals are + emitted. First, the media object will emit aboutToFinish() - + shortly before the playback has finished - and then finished(). + The stateChanged() signal will also be emitted with + \l{Phonon::}{PausedState}, which is the state the media object + takes when the playback is finished. If you wish to enter another + state, you can connect a slot to finished() and set a new state + there. + + The media object resolves the meta information, such as title, + artist, and album. The meta data is not resolved immediately after + a new source is provided, but will be resolved before the object + leaves the \l{Phonon::}{LoadingState}. The data is queried by + string keys - which should follow the Ogg Vorbis specification + \l http://xiph.org/vorbis/doc/v-comment.html - or by using the + \l{Phonon::}{MetaData} enum. The data available will depend on the + type and content of the individual media files. metaDataChanged() + will be emitted when the media object has resolved new meta data. + + Errors encountered during playback and loading of media sources + are reported by emitting a state changed signal with + \l{Phonon::}{ErrorState}. The severity of the error can be queried + by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, + it might be possible to continue the playback, for instance, if + only audio playback fails for a media source which also has video. + A \l{Phonon::}{FatalError} indicates that Phonon cannot continue + playback of the current source, but it is possible to try with a + different one. A user readable error message is given by + errorString(). + + \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, + {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, + Phonon::createPlayer(), {Phonon Module} + +*/ + +/*! + \property Phonon::MediaObject::transitionTime + \brief Defines the time between playback of two media sources + in the media queue. + + A positive transition time defines a gap of silence between queued + media sources. + + A transition time of 0 ms requests gapless playback (i.e., the + next source in the media queue starts immediately after the + playback of the current source finishes). + + A negative transition time defines a crossfade between the queued + media sources. + + Defaults to 0 (gapless playback). + + \warning This feature might not work reliably with every + backend. +*/ + +/*! + \property Phonon::MediaObject::prefinishMark + \brief the time when the prefinishMarkReached signal is emitted before playback ends. + + This property specifies the time in milliseconds the + prefinishMarkReached() signal is emitted before the playback + finishes. A value of \c 0 disables the signal. The signal is only + emitted for the last source in the \l{queue()}{media queue}. + + Defaults to \c 0 (disabled). + + \warning For some media data the total time cannot be determined + accurately, therefore the accuracy of the prefinishMarkReached signal + can be bad sometimes. Still, it is better to use this method than to + look at totalTime() and currentTime() to emulate the behavior + because the backend might have more information available than your + application does through totalTime() and currentTime(). + + \sa prefinishMarkReached() +*/ + +/*! + \property Phonon::MediaObject::tickInterval + \brief The time interval in milliseconds between two ticks. + + The tick() signal is emitted continuously during playback. + The tick interval is the time that elapses between the emission of two tick signals. + If you set the interval to \c 0 the tick signal gets disabled. + + The tick() signal can, for instance, be used to update widgets + that show the current position in the playback of a media source. + + Defaults to \c 0 (disabled). + + \warning The back-end is free to choose a different tick interval close + to what you asked for. This means that the following code \c may fail: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 + On the other hand the following is guaranteed: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 + + \sa tick() +*/ + +/*! + \fn Phonon::MediaObject::~MediaObject() + + Destroys the MediaObject. +*/ + +/*! + \fn State Phonon::MediaObject::state() const + + Returns the current Phonon::State of the object. + + \sa Phonon::State, stateChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::hasVideo() const + + Check whether the current media source includes a video stream. + + \warning This information is not resolved immediately after a + media object gets a new source. Listen to the hasVideoChanged() + signal instead. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 + + Returns \c true if the media contains video data; otherwise, + returns \c false. + + \sa hasVideoChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::isSeekable() const + + Check whether it is possible to seek, i.e., change the + playback position in the media stream. + + \warning This information is not solved immediately after the + media object gets a new media source. The hasVideoChanged() signal + is emitted after this information is available. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 + + Returns \c true if the current media may be seeked; otherwise, + returns \c false. + + \sa seekableChanged() +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(const QString &key) const + + Returns the strings associated with the given \a key. + + Backends should use the keys specified in the Ogg Vorbis + documentation: \l http://xiph.org/vorbis/doc/v-comment.html + + Therefore the following should work with every backend: + + Note that meta data is not resolved before the \c + metaDataChanged() signal is emitted. + + A typical usage looks like this: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const + + Returns the strings associated with the given \a key. + + Same as above except that the keys are defined in the + Phonon::MetaData enum. + + \sa metaDataChanged() +*/ + +/*! + \fn QMultiMap Phonon::MediaObject::metaData() const + + Returns all meta data in a multi map. + + \sa metaDataChanged() +*/ + +/*! + \fn QString Phonon::MediaObject::errorString() const + + Returns a human-readable description of the last error that occurred. + The strings given may vary between backends. + + The error description can be used to give a message to the user - + and the developer - when the stateChanged() signal is emitted with + \l{Phonon::}{ErrorState}. + + \section1 Qt Backends + + On Windows, Qt fetches its error messages from the DirectShow + backend. This usually includes an error number, which can be + looked up in the DirectShow documentation: + \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. + + On Linux and Mac, the error strings are not fetched directly from + the backend, but are created in the backend. + + \sa Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn ErrorType Phonon::MediaObject::errorType() const + + Tells your program what to do about the last error that occurred. + Use this function after receiving a stateChanged() signal with + \l{Phonon::}{ErrorState}. + + \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn MediaSource Phonon::MediaObject::currentSource() const + + Returns the current media source, i.e., the media source that is + being played back. The current source is either set with + setCurrentSource() or taken from the media queue() when a media + source has finished playing. + + \sa setCurrentSource() +*/ + +/*! + \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) + + Set the media source the MediaObject should use. + + After the media object receives a new source, it will enter the + \l{Phonon::}{LoadingState}. When it is ready to play, it + enters the \l{Phonon::}{StoppedState} unless another state + has been requested, e.g., by calling play(). + + \a source is the MediaSource object to the media data. You can + just as well use a QUrl or QString (for a local file) here. + + We show an example: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 + + \sa currentSource(), MediaSource +*/ + +/*! + \fn QList Phonon::MediaObject::queue() const + + Returns the queued media sources. + + This does list does not include the current source, + returned by currentSource(). + + \sa enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &sources) + + Set the \a sources to play when the current source has finished. + + This function will overwrite the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &urls) + + Set the \a urls to play when the current media has finished. + + This function overwrites the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const MediaSource &source) + + Appends \a source to the queue. + + You can use this function to provide the next source after the + aboutToFinish() signal has been emitted. + + \sa aboutToFinish(), setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &sources) + + Appends multiple \a sources to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &urls) + + Appends the URLs in \a urls to the media source queue. + + The function will create \l{MediaSource}s from the \l{QUrl}s, and + append these to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::clearQueue() + + Clears the queue of media sources. + + \sa queue(), enqueue() +*/ + +/*! + \fn qint64 Phonon::MediaObject::currentTime() const + + Returns the current time (in milliseconds), i.e., position in the + media stream, of the file currently being played. + + \sa tick(), totalTime(), remainingTime() +*/ + +/*! + \fn qint64 Phonon::MediaObject::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. + + Returns the total time in milliseconds. + + \warning The total time is not defined before the media object + enters the \l{Phonon::}{LoadingState}. + + \sa totalTimeChanged() +*/ + +/*! + \fn qint64 Phonon::MediaObject::remainingTime() const + + Get the remaining time (in milliseconds) of the file currently being played. + + Returns the remaining time in milliseconds. + + \sa totalTime(), currentTime(), totalTimeChanged() +*/ + +/*! + \fn void Phonon::MediaObject::play() + + Requests playback of the media data to start. + + Playback starts when the stateChanged() signal is emitted with + \l{Phonon::}{PlayingState}. + + If the media object is already in a + \l{Phonon::}{PlayingState}, nothing happens. + + \sa stop(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::pause() + + Requests playback to pause, and the media object to enter the + \l{Phonon::}{PausedState}. If it was paused already, nothing + changes. + + This function is asynchronous and the media might not be paused + immediately. + + \sa play(), stop(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::stop() + + Requests playback to stop, and the media object to enter the + \l{Phonon::}{StoppedState}. If it was stopped before + nothing changes. + + This function is asynchronous and the media might not be + stopped immediately. + + \sa play(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::seek(qint64 time) + + Requests a seek to the \a time indicated, specified in milliseconds. + + You can only seek if state() is PlayingState, BufferingState or PausedState. + + The call is asynchronous, so currentTime can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + If the current source of the media object is not seekable, calls + to this functions do nothing. + + \sa SeekSlider, tick() +*/ + +/*! + \fn void Phonon::MediaObject::clear() + + Stops and removes all playing and enqueued media sources. + + \sa setCurrentSource() +*/ + + +/*! + \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) + + This signal is emitted when the state of the MediaObject has changed. + The \a oldstate and \a newstate parameters indicate the previous + state and current state of the media object. + + If you are only interested in the new state of the media object, you can + connect this signal to a slot that accepts only one State argument. +*/ + +/*! + \fn void Phonon::MediaObject::tick(qint64 time) + + This signal is emitted in intervals defined by the + \l{tickInterval} property. The current position of the media + object in the stream is given by the \a time parameter. The \a + time is specified in milliseconds. + + \sa tickInterval +*/ + +/*! + \fn void Phonon::MediaObject::metaDataChanged() + + This signal is emitted when the media object has resolved new meta + data. This will happen before the media object leaves the + \l{Phonon::}{LoadingState} after a new source has been set. + + This signal is not emitted when the media object removes the + current data, i.e., when a new source is set or an error has + occurred. If you need to know this, you can listen for the + \l{Phonon::}{ErrorState}, and connect to the + \l{Phonon::MediaObject::}{currentSourceChanged()} signal. + + You can get the new meta data with the metaData methods. + + \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State +*/ + +/*! + \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) + + This signal is emitted when the media object's ability to seek in + the media stream changes. \a isSeekable is true if it is possible + to seek(); otherwise, it is false. + + Change in the ability to seek in the stream usually happens when + the current source changes or when an error occurs. + + \omit Emitted whenever the return value of isSeekable() + changes. \endomit + + Normally you'll check isSeekable() after setting a new media + source, and then let this signal tell you when seeking is + possible. That way you don't have to poll isSeekable(). +*/ + +/*! + \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) + + Emitted whenever the return value of hasVideo() changes, i.e., + the media source being played back contains video. + + Normally you'll check hasVideo() first and then let this signal + tell you whether video is available now or not. That way you + don't have to poll hasVideo(). + + \a hasVideo is true when the stream contains video and adding a + VideoWidget will show a video, and false if there is no video data + in the stream and adding a VideoWidget will show an empty (black) + VideoWidget. +*/ + +/*! + \fn void Phonon::MediaObject::bufferStatus(int percentFilled) + + Provides information about the status of the buffer. + + When a MediaObject is in the \l{Phonon::}{BufferingState}, it will + send this signal regularly. \a percentFilled is a number between 0 + and 100 telling you how much the buffer is filled. + + You can use this signal to show a progress bar to the user when + in BufferingState: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 + + Note that the \l{Phonon::}{BufferingState} is commonly used when + waiting for data over a network connection, but this might not be + true for all backends. +*/ + +/*! + \fn void Phonon::MediaObject::finished() + + Emitted when the object has finished playback. It is not emitted + if you call stop(), pause() or load(). It is emitted only when the + current media source has finished playing and the media queue() is + empty, or when a \l{Phonon::FatalError}{fatal error} occurs. + + \warning This signal is not emitted when the current source has + finished and there's another source in the queue. It is only + emitted when the queue is empty. + + \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) + + Emitted when the MediaObject fetches a new MediaSource from the + queue() and before it enters the \l{Phonon::}{LoadingState} for + the new source. The media object will take a new source from the + queue() when it has finished the playback of the + \l{currentSource()}{current source}. + + \a newSource is the source that starts to play at the time the + signal is emitted. +*/ + +/*! + \fn void Phonon::MediaObject::aboutToFinish() + + Emitted before the playback of the whole queue ends. When this + signal is emitted you still have time to enqueue() a new + MediaSource, so that playback continues. + + If you need a signal to be emitted at a specific time before + playback is finished, you should use the prefinishMarkReached() + signal instead. + + \sa enqueue(), prefinishMark, prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) + + Emitted when there are only \a msecToEnd milliseconds left + of playback. + + \warning This signal is not emitted when there is another source + in the queue. It is only emitted when the queue is empty. + + \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() +*/ + +/*! + \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) + + This signal is emitted as soon as the total time of the media file is + known or has changed. For most non-local media data the total + time of the media can only be known after some time. At that time the + totalTime function can not return useful information. You have + to wait for this signal to know the real total time. + + \a newTotalTime is the length of the media file in milliseconds. + + \sa totalTime() +*/ + +/*! + \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) + + Convenience function to create a MediaObject and AudioOutput + connected by a path. The \l{Phonon::}{MediaObject} return will + have \a source set as its current source and the specified \a + category. + +*/ + +/*! + \class Phonon::MediaObjectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::BackendCapabilities + \inmodule Phonon + \since 4.4 + \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. + +*/ + +/*! + \class Phonon::BackendCapabilitiesPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::BackendCapabilities::Notifier + \since 4.4 + \inmodule Phonon + \inheaderfile Phonon/BackendCapabilities + + Notifications about backend capabilities. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() + + This signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() + + This signal is emitted when audio output devices were plugged or + unplugged. + + Check BackendCapabilities::availableAudioOutputDevices to get the + current list of available devices. +*/ + +/*! + \fn Notifier *Phonon::BackendCapabilities::notifier() + + Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. + + \return a pointer to a QObject. + + The capabilitiesChanged signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. + + To connect to this signal do the following: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 + + \sa Notifier::capabilitiesChanged() +*/ + +/*! + \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() + + Returns a list of mime types that the Backend can decode. + + \sa isMimeTypeAvailable() +*/ + +/*! + \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) + + Often all you want to know is whether one given MIME type can be + decoded by the backend. Use this method in favor of + availableMimeTypes() as it can give you a negative answer without + having a backend loaded. + + Returns true if the given \a mimeType is supported by the backend; + otherwise, returns false. + + \sa availableMimeTypes() +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioOutputDevices() + + Returns the audio output devices the backend supports. + + \return A list of AudioOutputDevice objects that give a name and + description for every supported audio output device. +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioEffects() + + Returns descriptions for the audio effects the backend supports. + + \return A list of AudioEffectDescription objects that give a name and + description for every supported audio effect. +*/ + +/*! + \internal + \class ObjectDescriptionModelData + \internal + \inmodule Phonon + \brief Data class for models for ObjectDescription objects. +*/ + +/*! + \typedef Phonon::EffectDescription + \relates Phonon::ObjectDescription + + EffectDescription gives a description of an \l{Processors}{audio + effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} + class. Please see its class description for details. + + EffectDescription is used to create audio \l{Phonon::}{Effect}s, + which can be inserted into a media graph, altering an audio + stream. + + \sa Phonon::ObjectDescription, {Capabilities Example}, {Media + Player} + +*/ + +/*! + \class Phonon::ObjectDescriptionModel + \inmodule Phonon + \internal + \since 4.4 + \brief The ObjectDescriptionModel class provides a model from + a list of ObjectDescription objects. + + ObjectDescriptionModel is a read only model that supplies a list + using ObjectDescription::name() for the text and + ObjectDescription::description() for the tooltip. If set the properties + "icon" and "available" are used to set the decoration and disable the + item (disabled only visually, you can still select and drag it). + + It also provides the methods moveUp() and moveDown() to order the list. + Additionally drag and drop is possible so that + QAbstractItemView::InternalMove can be used. + The resulting order of the ObjectDescription::index() values can then be + retrieved using tupleIndexOrder(). + + An example use case would be to give the user a QComboBox to select + the output device: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 + + And to retrieve the selected AudioOutputDevice: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 + +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const + + Returns the number of rows in the model. This value corresponds + to the size of the list passed through setModelData. + + \param parent The optional \a parent argument is used in most models to specify + the parent of the rows to be counted. Because this is a list if a + valid parent is specified the result will always be 0. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::rowCount() +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const + + Returns data from the item with the given \a index for the specified + \a role. + If the view requests an invalid index, an invalid variant is + returned. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::data(), Qt::ItemDataRole +*/ + +/*! + \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const + \internal + + Reimplemented to show unavailable devices as disabled (but still + selectable). The \a index of the model index for which to return + flags. + +*/ + +/*! + \fn inline QList Phonon::ObjectDescriptionModel::tupleIndexOrder() const + + Returns a list of indexes in the same order as they are in the + model. The indexes come from the ObjectDescription::index + method. + + This is useful to let the user define a list of preference. +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const + + Returns the ObjectDescription::index for the tuple + at the given position \a positionIndex. For example a + QComboBox will give you the currentIndex as the + position in the list. But to select the according + AudioOutputDevice using AudioOutputDevice::fromIndex + you can use this method. + + \param positionIndex The position in the list. +*/ + +/*! + \class Phonon::ObjectDescriptionModelDataPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const + \internal + + Returns the MIME data that dropMimeData() can use to create new + items. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) + + Moves the item at the given \a index up. In the resulting list + the items at index.row() and index.row() - 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) + + Moves the item at the given \a index down. In the resulting list + the items at index.row() and index.row() + 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList > &data, QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent and the given \a data. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList > &data) + + Sets the model data using the list provided by \a data. + + All previous model data is cleared. +*/ + +/*! + \fn inline QList > Phonon::ObjectDescriptionModel::modelData() const + + Returns the model data. + + As the order of the list might have changed this can be different + to what was set using setModelData(). +*/ + +/*! + \fn inline ObjectDescription Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const + + Returns one ObjectDescription of the model data for the given \a index. +*/ + +/*! + \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const + + This model supports drag and drop to copy or move + items. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) + + Accept drops from other models of the same ObjectDescriptionType. + + The \a data is dropped at the given \a row and \a column; you + also receive the \a parent model index. + + If a valid \a parent is given the dropped items will be inserted + above that item. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) + + Removes count rows starting with the given row. + + If a valid \a parent is given no rows are removed since this is a + list model. + + Returns true if the rows were successfully removed; otherwise returns false. +*/ + +/*! + \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const + + Returns a list of supported drag and drop MIME types. Currently + it only supports one type used internally. +*/ + +/*! + \class Phonon::EffectInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::Effect + \inmodule Phonon + \inheaderfile Phonon/Effect + \since 4.4 + \brief The Effect class is used to transform audio streams. + + An effect is a media node which is inserted into a path between a + \l{Phonon::}{MediaObject} and an audio output node, for instance, + an \l{Phonon::}{AudioOutput}. The Effect transforms the media + stream on that path. + + Examples may include simple modifiers, such as fading or pitch + shifting, and more complex mathematical transformations. You can + query the backend for available effects with + BackendCapabilities::availableAudioEffects(). Note that the + effects available is dependent on the underlying system + (DirectDraw, GStreamer, or QuickTime). + + In order to use an effect, insert it into the path as follows: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 + + The effect will immediately begin applying it's transformations on + the path. To stop it, remove the Effect from the path. + + To create an effect, you use the \l{Phonon::}{EffectDescription} + class, which you get from + \l{BackendCapabilities::}{availableAudioEffects()}. We give a code + example below. + + \snippet doc/src/snippets/audioeffects.cpp 0 + + An effect can have one or more parameters, which let you alter how + the effect works, for instance, by specifying the depth of a + reverb effect. See the EffectParameter class description for + details. + + Phonon also provides EffectWidget, which lets the user modify the + parameters of an effect an the fly; e.g., with combo boxes. + + \sa {Phonon Module}, EffectWidget +*/ + +/*! + \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) + + Constructs a new effect object with the given \a description and \a parent object. + + The EffectDescription object determines the type of the effect. + + \sa {Phonon::BackendCapabilities::availableAudioEffects()} +*/ + +/*! + \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) + \internal +*/ + +/*! + \fn Phonon::Effect::~Effect() + \internal +*/ + +/*! + \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const + + Returns the value of the given effect \a parameter. You can fetch + the available parameters for an effect with parameters(). + + \sa setParameterValue(), EffectParameter +*/ + +/*! + \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) + + Sets the given effect \a parameter to the specified \a value. + + Parameters for an effect are returned by parameters(). You can + check which QVariant::Type an EffectParameter takes with the + EffectParameter::type() function. + + \sa parameterValue(), EffectParameter +*/ + +/*! + \fn EffectDescription Phonon::Effect::description() const; + + Returns the description of this effect. This is the same + description that was passed to the constructor. +*/ + +/*! + \fn QList Phonon::Effect::parameters() const; + + Returns a list of parameters that this effect provides to control + its behavior. + + \sa EffectParameter, EffectWidget +*/ + +/*! + \class Phonon::EffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::AudioOutput + \inmodule Phonon + \inheaderfile Phonon/AudioOutput + \since 4.4 + \brief The AudioOutput class is used to send data to audio output devices. + + The AudioOutput class plays sound over a sound device. The audio + output needs to be connected to a \l{Phonon::}{MediaObject} using + \l{Phonon::}{createPath()}. To start playback, you call + \l{Phonon::MediaObject::}{play()} on the media object. + + \snippet snippets/phonon.cpp 2 + + The class supports changing the volume(). It is also possible to + mute the sound. + + To find out what \l{Phonon::}{AudioOutputDevice}s are available + for AudioOutput, you can call + BackendCapabilities::availableAudioOutputDevices(). A default device is + selected by the backend, but it is possible to set the device to + be used with setOutputDevice(). The outputDeviceChanged() signal + will be emitted if the device changes. + + If an error occurs with the playback, for instance, if no valid + output device is found, the media object will receive a + stateChanged() signal with the \l{Phonon::}{ErrorState}. + + Note that the default values of properties are dependent on the + backend. + + \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} +*/ + +/*! + \property Phonon::AudioOutput::name + + This is the name that appears in Mixer applications that control + the volume of this output. + +*/ + +/*! + \property Phonon::AudioOutput::volume + + This is the current loudness of the output. \omit The volume is a + real value between 0.0 (minimum) and 1.0 (maximum). The volume + follows the sound device used, with 1.0 being the maximum volume + the device can produce. \endomit + + (it is using Stevens' law + to calculate the change in voltage internally). + + \sa volumeDecibel +*/ + +/*! + \property Phonon::AudioOutput::volumeDecibel + + This is the current volume of the output in decibel. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::AudioOutput::outputDevice + This property holds the (hardware) destination for the output. + + The default device is determined by the \l{Phonon::}{Category} and the global + configuration for that category. Normally you don't need + to override this setting - letting the user change the global + configuration is the right choice. You can still override the + device though, if you have good reasons to do so. + + \sa outputDeviceChanged() +*/ + +/*! + \property Phonon::AudioOutput::muted + This property tells whether the output is muted. + + Muting the output has the same effect as calling setVolume(0.0). +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) + + Creates a new AudioOutput with the given \a parent that defines + output to a physical device. + + The \a category can be used by mixer applications to group volume + controls of applications into categories. That makes it easier for + the user to identify the programs. + The category is also used for the default output device that is + configured centrally. As an example: often users want to have the + audio signal of a VoIP application go to their USB headset while + all other sounds should go to the internal soundcard. + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) + + Creates a new AudioOutput that defines output to the system + default device with the \{Phonon::Category::}{NoCategory} category + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn Phonon::Category Phonon::AudioOutput::category() const + + Returns the category of this output. + + \sa Phonon::AudioOutput::AudioOutput() +*/ + +/*! + \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) + + This signal is emitted whenever the volume has changed. As the + volume can change without a call to setVolume (calls over dbus) + this is important to keep a widget showing the current volume up + to date. + + \a newVolume is the new volume level. + + \sa setVolume(), volume() +*/ + +/*! + \fn void Phonon::AudioOutput::mutedChanged(bool muted) + + This signal is emitted when the muted property has changed. The \a muted + value passed by the signal indicates the state of the muted property. + As this property can change by IPC (DBus) calls a UI element showing + the muted property should listen to this signal. +*/ + +/*! + \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) + + This signal is emitted when the (hardware) device for the output + has changed. \a newAudioOutputDevice is the new device. + + The change can happen either through setOutputDevice or if the + global configuration for the used category has changed. + + \sa outputDevice +*/ + +/*! + \class Phonon::AudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameter + \inmodule Phonon + \inheaderfile Phonon/EffectParameter + \since 4.4 + \brief The EffectParameter class describes one parameter of an effect. + + You fetch the parameters of an \l{Phonon::}{Effect} with + \l{Phonon::}{Effect::parameters()}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 0 + + To describe itself, an effect parameter gives a name() and + possibly description() (depending on the backend used). These are + suited to present the effect parameter to the user of a Phonon + application. + + Note that effects are created by the backend, and that + their name and descriptions may vary. + + The value of an effect parameter is stored in a \l{QVariant}, + of which type() is usually \c int or \c double. + + The value is retrieved with \l{Phonon::}{Effect::parameterValue()} + and set with \l{Phonon::Effect::}{setParameterValue()} - both of + which takes the EffectParameter as argument. Note that not all + effect parameters support setting of their value. + + You get the values a parameter can take with possibleValues(); an + empty list is returned if the values are continuous. + + A parameter may also specify default(), minimum(), and maximum() + values. Values are returned as \l{QVariant}s. If the parameter + does not have the requested value, an \l{QVariant::Invalid} + invalid QVariant is returned from these functions. + + The \l{Phonon::}{EffectWidget} provides a widget with which one + can control the parameters of an \l{Phonon::}{Effect}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 1 + + \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter() + \internal + + Creates an invalid effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::~EffectParameter() + + Destroys the effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) + + Constructs a copy of the \a other effect parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::name() const + + The name of the parameter. Can be used as the label. + + \return A label for the parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::description() const + + The parameter may come with a description (LADSPA doesn't have a + field for this, so don't expect many effects to provide a + description). + + The description can be used for a tooltip or WhatsThis help. + + \return A text describing the parameter. +*/ + +/*! + \fn QVariant::Type Phonon::EffectParameter::type() const + + Returns the parameter type. + + Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When + QVariant::String is returned you get the possible values from possibleValues. +*/ + +/*! + \fn bool Phonon::EffectParameter::isLogarithmicControl() const + + Returns whether the parameter should be + displayed using a logarithmic scale. This is particularly useful for + frequencies and gains. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::minimumValue() const + + The minimum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + below. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::maximumValue() const + + The maximum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + above. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::defaultValue() const + + The default value. +*/ + +/*! + \fn QVariantList Phonon::EffectParameter::possibleValues() const + + The possible values to be used for the control to edit the parameter. + + if the value of this parameter is to be picked from predefined values + this returns the list (otherwise it returns an empty QVariantList). +*/ + +/*! + \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) + + Assigns the \a other effect parameter to this parameter and returns + a reference to this parameter. +*/ + +/*! + \enum Phonon::EffectParameter::Hint + + Only for backend developers: + + Flags to set the return values of isToggleControl(), + isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and + isBoundedAbove(). The values of the flags correspond to the values + used for LADSPA effects. + + \value ToggledHint + If this hint is set it means that + the control has only two states: zero and non-zero + (see isToggleControl()). + + \value LogarithmicHint + LADSPA's SAMPLE_RATE hint needs to be translated by the backend + to normal bounds, as the backend knows the sample rate - and the + frontend doesn't (see isLogarithmicControl()). + + \value IntegerHint See isIntegerControl(). +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(int parameterId, + const QString &name, EffectParameter::Hints hints, + const QVariant &defaultValue, const QVariant &min = QVariant(), + const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), + const QString &description = QString()) + + Only to be used by backend implementations: + + Creates a new effect parameter. + + \a parameterId This is a number to uniquely identify the + parameter. The id is used for value() and setValue(). + + \a name is the name/label for this parameter. + + \a hints sets the hints for the type of parameter. + + \a defaultValue The value that should be used as a default. + + \a min is the minimum value allowed for this parameter. You only + need to set this if the BoundedBelowHint is set. + + \a max is the maximum value allowed for this parameter. You only + need to set this if the BoundedAboveHint is set. + + The \a values parameter is the values that the effect parameter + can take (only applies if non-continuous) + + \a description is a descriptive text for the parameter + (explaining what it controls) to be used as a tooltip or + WhatsThis help. +*/ + +/*! + \fn int Phonon::EffectParameter::id() const + + \internal + + Returns the parameter's identifier. +*/ + +/*! + \typedef Phonon::AudioOutputInterface + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AudioOutputInterface40 + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for AudioOutput objects + +*/ + +/*! + \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() + \internal +*/ + +/*! + \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 + \internal +*/ + +/*! + \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 + \internal +*/ + +/*! + \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 + \internal +*/ + +/*! + \class Phonon::Path + \inmodule Phonon + \inheaderfile Phonon/Path + \since 4.4 + \brief The Path class describes connections between media nodes. + + In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s + are connected by Paths. The multimedia travels in streams over + these paths. + + You create a path between two media nodes using the static + Phonon::createPath() function, which takes two nodes as arguments. + The first argument will send the media stream to the second. + Please refer to the class description of the individual media + nodes and the Phonon \l{Phonon Overview}{overview} to see which + nodes can be connected to each other. + + Paths are also used to insert audio \l{Phonon::}{Effect}s between + two media nodes. The effect will then alter the stream on the + path. Notice that \l{Phonon::}{Effect}s also are media nodes, but + that insertEffect() - instead of Phonon::createPath() - is used to + insert them into the media graph. + + The following code example shows how to create a path between two + media nodes and insert an effect on that path. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 + + \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, + Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn Phonon::Path::~Path(); + + Destroys this reference to the Path. If the path was valid the connection is not broken + as both the source and the sink MediaNodes still keep a reference to the Path. + + \sa disconnect() +*/ + +/*! + \fn Phonon::Path::Path(); + + Creates an invalid path. + + You can still make it a valid path by calling reconnect. It is + recommended to use the Phonon::createPath() function to create + paths. + + \sa Phonon::createPath(), isValid() +*/ + +/*! + \fn Phonon::Path::Path(const Path &path); + + Constructs a copy of the other \a path specified. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::isValid() const; + + A path is considered valid if it is connected to two media nodes, + in which case this function returns true. If it is connected to + one or no media nodes, it is consider invalid, and this function + will then return false. +*/ + +/*! + \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); + + Creates and inserts an effect into the path. + + You may insert effects of the same class as often as you like, + but if you insert the same object, the call will fail. + + \a desc is the EffectDescription object for the effect to be inserted. + + If you already inserted an effect you can + tell with \a insertBefore in which order the data gets + processed. If this is \c 0 the effect is appended at the end of + the processing list. If the effect has not been inserted before + the method will do nothing and return \c false. + + Returns a pointer to the effect object if it could be inserted + at the specified position. If \c 0 is returned, the effect was not + inserted. + + Below is a code example for inserting an effect into a path: + + \snippet doc/src/snippets/audioeffects.cpp 0 + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); + + Inserts the given \a effect into the path before the effect specified by \a insertBefore + and returns true if successful; otherwise returns false. + + If \a insertBefore is zero, the effect is appended to the processing list. + + You may insert effects of the same class as often as you like, but if you insert + the same object, the call will fail. + + \a effect will be inserted right before \a insertBefore. If + \a insertBefore is \c 0, the effect is appended at the end of the + processing list. If the effect has not been inserted before the + method will do nothing and return \c false. + + Returns whether the effect could be inserted at the specified + position. If \c false is returned the effect was not inserted. + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::removeEffect(Effect *effect); + + Removes the given \a effect from the path and returns true; otherwise returns false. + + Removes an \a effect from the path. + + If the effect is deleted while it is still connected, the effect will be removed + automatically. + + \omit + \param effect The effect to be removed. + + \return Returns whether the call was successful. If it returns + \c false the effect could not be found in the path, meaning it + has not been inserted before. + \endomit + + \sa insertEffect(), effects() +*/ + +/*! + \fn QList Phonon::Path::effects() const; + + Returns a list of Effect objects that are currently + used as effects. The order in the list determines the order the + signal is sent through the effects. + + \return A list with all current effects. + + \sa insertEffect(), removeEffect() +*/ + +/*! + \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); + + Changes the media nodes the path is connected to by connecting the path + to the \a source and \a sink nodes specified. Returns true if successful; + otherwise returns false. + + If unsuccessful, the path remains connected to the same nodes as before. + + \sa Phonon::createPath(), {Phonon Overview} +*/ + +/*! + \fn bool Phonon::Path::disconnect(); + + Tries to disconnect the path from the MediaNodes it is connected to, returning + true if successful or false if unsuccessful. + + If successful, the path is invalidated: isValid() will returns false. +*/ + +/*! + \fn Path &Phonon::Path::operator=(const Path &p); + + Assigns \a p to this Path and returns a reference to this Path. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::operator==(const Path &p) const; + + Returns true if this Path is equal to \a p; otherwise returns false; +*/ + +/*! + \fn bool Phonon::Path::operator!=(const Path &p) const; + + Returns true if this Path is not equal to \a p; otherwise returns false. +*/ + +/*! + \fn MediaNode *Phonon::Path::source() const; + + Returns the source MediaNode used by the path. +*/ + +/*! + \fn MediaNode *Phonon::Path::sink() const; + + Returns the sink MediaNode used by the path. +*/ + +/*! + \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); + + \relates Phonon::Path + Creates a new Path connecting the two MediaNodes \a source and \a sink. + + The implementation will automatically select the right format and media type. E.g. connecting a + MediaObject and AudioOutput will create a Path object connecting the audio. This might be + represented as PCM or perhaps even AC3 depending on the AudioOutput object. + + \param source The MediaNode to connect an output from + \param sink The MediaNode to connect to. +*/ + +/*! + \class Phonon::PathPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObjectInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Backend interface for media sources. + + The backend implementation has to provide two signals, that are not defined + in this interface: + \list + \o \target phonon_MediaObjectInterface_stateChanged + void stateChanged(Phonon::State newstate, Phonon::State oldstate) + + Emitted when the state of the MediaObject has changed. + In case you're not interested in the old state you can also + connect to a slot that only has one State argument. + + \param newstate The state the Player is in now. + \param oldstate The state the Player was in before. + + \o \target phonon_MediaObjectInterface_tick + void tick(qint64 time) + + This signal gets emitted every tickInterval milliseconds. + + \param time The position of the media file in milliseconds. + + \sa setTickInterval() + \sa tickInterval() + \endlist + + \sa MediaObject +*/ + +/*! + \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() + \internal +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::play() = 0 + \internal + + Requests the playback to start. + + This method is only called if the state transition to PlayingState is possible. + + The backend should react immediately + by either going into PlayingState or BufferingState if the + former is not possible. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::pause() = 0 + \internal + + Requests the playback to pause. + + This method is only called if the state transition to PausedState is possible. + + The backend should react as fast as possible. Go to PausedState + as soon as playback is paused. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::stop() = 0 + \internal + + Requests the playback to be stopped. + + This method is only called if the state transition to StoppedState is possible. + + The backend should react as fast as possible. Go to StoppedState + as soon as playback is stopped. + + A subsequent call to play() will start playback at the beginning of + the media. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 + \internal + + Requests the playback to be seeked to the given time. + + The backend does not have to finish seeking while in this function + (i.e. the backend does not need to block the thread until the seek is + finished; even worse it might lead to deadlocks when using a + ByteStream which gets its data from the thread this function would + block). + + As soon as the seek is done the currentTime() function and + the tick() signal will report it. + + \param milliseconds The time where playback should seek to in + milliseconds. +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 + \internal + + Return the time interval in milliseconds between two ticks. + + Returns the tick interval that it was set to (might not + be the same as you asked for). +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 + \internal + + Change the interval the tick signal is emitted. Set \a interval to 0 to + disable the signal. + + \a interval tick interval in milliseconds + + Returns the tick interval that it was set to (might not be the same as you + asked for). + +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 + \internal + + Check whether the media data includes a video stream. + + Returns true if the media contains video data. +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 + \internal + + If the current media may be seeked this function returns true; + otherwise, false. + + Returns whether the current media may be seeked. +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 + \internal + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 + \internal + + Get the current state. +*/ + +/*! + \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 + \internal + + A translated string describing the error. +*/ + +/*! + \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 + \internal + + Tells your program what to do about the error. + + \sa Phonon::ErrorType +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 + \internal + + Returns the total time of the media in milliseconds. + + If the total time is not know return -1. Do not block until it is + known, instead emit the totalTimeChanged signal as soon as the total + time is known or changes. +*/ + +/*! + \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 + \internal + + Returns the current source. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 + \internal + + Sets the current source. When this function is called the MediaObject is + expected to stop all current activity and start loading the new + source (i.e. go into LoadingState). + + It is expected that the + backend now starts preloading the media data, filling the audio + and video buffers and making all media meta data available. It + will also trigger the totalTimeChanged signal. + + If the backend does not know how to handle the source it needs to + change state to Phonon::ErrorState. Don't bother about handling KIO + URLs. It is enough to handle AbstractMediaStream sources correctly. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 + \internal + + Sets the next source to be used for transitions. When a next source + is set playback should continue with the new source. In that case + finished and prefinishMarkReached are not emitted. + + \param source The source to transition to (crossfade/gapless/gap). If + \a source is an invalid MediaSource object then the queue is empty + and the playback should stop normally. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget + \inmodule Phonon + \inheaderfile Phonon/EffectWidget + \since 4.4 + \brief The EffectWidget class provides a widget to control the parameters of an Effect. + + The EffectWidget class provides a widget, with which an effects + parameters can be controlled. The widget does not have an API, + and is constructed with the \l{Phonon::}{Effect}, of which + parameters should be controlled. + + \snippet doc/src/snippets/audioeffects.cpp 1 + + The following image shows an example of an effect widget. + + \image effectwidget.png + + Note that some audio effects do not have parameters, and the + widget will then not \l{QWidget::}{show()} at all. + + \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} +*/ + +/*! + \class Phonon::AbstractAudioOutput + \inmodule Phonon + \internal + \brief Provides a common base class for all audio outputs. + + \sa AudioOutput +*/ + +/*! + \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() + \internal +*/ + +/*! + \class Phonon::AbstractAudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputAdaptor + \inmodule Phonon + \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput + \internal +*/ + +/*! + \class Phonon::VolumeSlider + \inmodule Phonon + \inheaderfile Phonon/VolumeSlider + \since 4.4 + \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. + + The slider also displays an icon indicating if the volume of the + \l{Phonon::}{AudioOutput} it is connected to is muted. The icon + can be removed with setMuteVisible(). + + It is possible to set the \l{maximumVolume}{maximum} value of the + slider. By default, the minimum and maximum values of the slider + are 0.0 (no sound) to 1.0 (the maximum volume the audio output can + produce). + + Here follows a code example: + + \snippet doc/src/snippets/volumeslider.cpp 0 + + \omit mention how to change the style of the slider. \endomit + + \sa {Phonon Module} +*/ + +/*! + \property Phonon::VolumeSlider::maximumVolume + + This property holds the maximum volume that can be set with this slider. + + By default the maximum value is 1.0 (100%). +*/ + +/*! + \property Phonon::VolumeSlider::orientation + This property holds the orientation of the slider. + + The orientation must be Qt::Vertical (the default) or Qt::Horizontal. +*/ + +/*! + \property Phonon::VolumeSlider::tracking + This property holds whether slider tracking is enabled. + + If tracking is enabled (the default), the volume changes + while the slider is being dragged. If tracking is + disabled, the volume changes only when the user + releases the slider. +*/ + +/*! + \property Phonon::VolumeSlider::pageStep + This property holds the page step. + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 (5% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::singleStep + This property holds the single step. + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 1 (1% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::muteVisible + This property holds whether the mute button/icon next to the slider is visible. + + By default the mute button/icon is visible. +*/ + +/*! + \property Phonon::VolumeSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) + Constructs a new volume slider with the given \a parent. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) + Constructs a new volume slider with the given \a output object and \a parent. +*/ + +/*! + \fn Phonon::VolumeSlider::~VolumeSlider() +*/ + +/*! + \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const +*/ + +/*! + \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) + + Sets the audio output object to be controlled by this slider to the specified + \a output object. +*/ + +/*! + \class Phonon::VolumeSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaController + \inmodule Phonon + \inheaderfile Phonon/MediaController + \since 4.4 + \brief The MediaController class controls optional features of a media file/device. + + Some media sources have content that the \l{Phonon::}{MediaObject} + does not provide control over, for instance, chapters in a DVD + file. The functionality the media controller offers is + dependent on the type of media source that is played back. + Commonly, the media controller allows you to: + + \list + \o Navigate between \bold chapters. + \o Navigate between \bold titles. + \o Select between \bold angles. + \endlist + + The \l{Phonon::MediaController::}{Feature} enum explains these + terms in more detail, and their context in playback of CD and DVD. + + The media controller keeps a \l{Phonon::}{MediaObject}, of which + \l{Phonon::MediaObject::currentSource()}{media source} is played + back. You can still call the media object's functions, e.g., + \l{Phonon::MediaObject::}{stop()}; this is all handled correctly + by the media controller. You have the option of letting the media + controller play all titles of a source in sequence by setting the + \l{autoplayTitles()}{autoplay titles} option. + + To start a playback using a media object, you call + \l{Phonon::MediaObject::}{play()} on the media object. To play a + specific title, use setCurrentTitle() and then call + \l{Phonon::MediaObject::}{play()}. + + \warning The Phonon::MediaController class is not yet supported by + Qt backends. + + \sa {Phonon Module} +*/ + +/*! + \fn int Phonon::MediaController::availableAudioChannels() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableAudioChannelsChanged() + \internal +*/ + +/*! + \fn QList Phonon::MediaController::availableSubtitles() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableSubtitlesChanged() + \internal +*/ + +/*! + \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const + \internal +*/ + +/*! + \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() + \internal +*/ + +/*! + \enum Phonon::MediaController::Feature + + The values of this enum are interpreted differently depending on + the type of media source, e.g., DVD or CD. We give examples for + these sources. + + \value Angles In the VOB (DVD) format, it is possible to to give + several video streams of the same scene, each of which displays + the scene from a different angle. The DVD viewer can then change + between these angles. + + \value Chapters In the VOB format, chapters are points in a + single video stream that can be played and seeked to + separately. + + \value Titles On a CD, a title is a separate sound track. On DVD, + a title is a separate VOB file. + +*/ + +/*! + \fn Phonon::MediaController::MediaController(MediaObject *parent) + + Constructs a new MediaController with the media object (\a parent) + to be used by the media controller. + + \sa MediaObject, Feature +*/ + +/*! + \fn Phonon::MediaController::~MediaController() +*/ + +/*! + \fn Features Phonon::MediaController::supportedFeatures() const +*/ + +/*! + \fn int Phonon::MediaController::availableAngles() const + + Returns the available angles that is available for the current + media source. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentAngle() const + + Returns the angle that is currently used. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableChapters() const + + Returns the number of chapters the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentChapter() const + + Returns the chapter that is currently being played back. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableTitles() const + + Returns the number of titles that the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentTitle() const + + Returns the title that is currently played back. + + The current title is 0 (the first) by default. + + \sa Feature +*/ + +/*! + \fn bool Phonon::MediaController::autoplayTitles() const + + Returns true if titles will automatically be played when the media + is played; otherwise returns false. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa setAutoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setAutoplayTitles(bool enable) + + Sets the titles to play automatically when the media is played if + \a enable is true; otherwise disables this option. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa autoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) + + Sets the current angle to the given \a angleNumber if the media + file or device supports navigation by angle number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) + + Sets the current chapter to the given \a chapterNumber if the media + file or device supports navigation by chapter number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) + + Skips to the given title \a titleNumber. + + If it was playing before the title change it will start playback on the new title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::nextTitle() + + Skips to the next title. + + If it was playing before the title change it will start playback on the next title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::previousTitle() + + Skips to the previous title. + + If it was playing before the title change it will start playback on the previous title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) + + This signal is emitted whenever the number of available angles changes. + The new number of available angles is given by \a availableAngles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::angleChanged(int angleNumber) + + This signal is emitted whenever the current angle changes. + The new angle number is given by \a angleNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) + + This signal is emitted whenever the number of available chapters changes. + The new number of available chapters is given by \a availableChapters. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::chapterChanged(int chapterNumber) + + This signal is emitted whenever the current chapter changes. + The new chapter number is given by \a chapterNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) + + This signal is emitted whenever the number of available titles changes. + The new number of available titles is given by \a availableTitles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::titleChanged(int titleNumber) + + This signal is emitted whenever the current title changes. + The new title number is given by \a titleNumber. + + \sa Feature +*/ + +/*! + \class Phonon::VideoWidget + \inmodule Phonon + \inheaderfile Phonon/VideoWidget + \since 4.4 + \ingroup advanced + \ingroup multimedia + \brief The VideoWidget class provides a widget that is used to display video. + + The VideoWidget class renders the video of a media stream on a + QWidget. It is connected to the \l{Phonon::}{MediaObject}, of + which video stream it should render. You connect the two objects + using the Phonon::createPath() function. + + The widget has some possibilities to manipulate the video + stream. You can change the brightness(), hue(), saturation(), + and contrast(). + + Resizing of the video is handled automatically, but you can affect + the way the video is resized with the aspectRatio and scaleMode + properties. By default, the widget will use the aspect ratio of + the video stream itself. + + The video widget takes the size of the video when it receives a new video + stream (i.e., when a new MediaSource is set on the MediaObject to which it is + connected). If you need to know the size of the video, you can call + \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the + MediaObject leaves the \l{Phonon::}{LoadingState}). + + It is also possible to go to \l{fullScreen}{full screen} mode. + + A typical example of usage follows below: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 + + \sa {Phonon Module} +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) + \internal + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn bool Phonon::VideoWidget::event(QEvent *) + \reimp +*/ + +/*! + \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) + \reimp +*/ + +/*! + \enum Phonon::VideoWidget::ScaleMode + + The ScaleMode enum describes how to treat aspect ratio during + resizing of video. + + \value FitInView The video will be fitted to fill the view + keeping aspect ratio. + \value ScaleAndCrop The video is scaled +*/ + +/*! + \property Phonon::VideoWidget::fullScreen + This property holds whether the video is shown using the complete + screen. + + The property differs from QWidget::fullScreen in that it is + writeable. + + By default the widget is not shown in fullScreen. + + \warning When switching to full screen mode using setFullScreen(), + the widget onto which the video is rendered is shown as a + top-level window. Key event forwarding is handled by VideoWidget, + but if you need to handle other events, e.g., mouse events, you + should handle fullscreen mode yourself. +*/ + +/*! + \property Phonon::VideoWidget::aspectRatio + Defaults to AspectRatioAuto. + + \sa AspectRatio +*/ + +/*! + \property Phonon::VideoWidget::scaleMode + + If the size of the widget and the size of the video are not equal. + The video will be zoomed to fit the widget. The smaller zoom + (AddBarsScaleMode) adds black bars at the left/right or top/bottom to + make all of the image visible (default). The bigger zoom (ExpandMode) + fills the widget completely, keeping all information in one direction + and leaving parts of the image outside of the widget in the other + direction. +*/ + +/*! + \property Phonon::VideoWidget::brightness + + This property holds brightness of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::contrast + + This property holds the contrast of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::hue + + This property holds the hue of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::saturation + + This property holds saturation of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \enum Phonon::VideoWidget::AspectRatio + + Defines the width:height to be used for the video. + + \value AspectRatioAuto + Let the decoder find the aspect ratio automatically from the + media file (this is the default). + + \value AspectRatioWidget + Fits the video into the widget making the aspect ratio depend + solely on the size of the widget. This way the aspect ratio + is freely resizeable by the user. + + \value AspectRatio4_3 + Make width/height == 4/3, which is the old TV size and + monitor size (1024/768 == 4/3). (4:3) + + \value AspectRatio16_9 + Make width/height == 16/9, which is the size of most current + media. (16:9) +*/ + +/*! + \fn void Phonon::VideoWidget::exitFullScreen() + + Convenience slot, calling setFullScreen(false) +*/ + + +/*! + \fn void Phonon::VideoWidget::enterFullScreen() + + Convenience slot, calling setFullScreen(true) +*/ + +/*! + \class Phonon::VideoWidgetInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() +*/ + +/*! + \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 + \internal +*/ + +/*! + \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 + \internal +*/ + +/*! + \class Phonon::PlatformPlugin + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 + + Creates a AbstractMediaStream object with the given \a parent that provides the data + for the given URL specified by \a url. + \omit + On KDE this uses KIO. + \endomit +*/ + +/*! + \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 + + Returns the icon for the given icon name. +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, + const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 + + Shows a notification pop-up with the given \a notificationName and \a text. + Each action in the associated list of \a actions is connected to the \a actionSlot + of the specified \a receiver object, which is expected to act on the actions as + they are triggered by the user. +*/ + +/*! + \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 + + Returns the name of the application. For most Qt application this is + QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. +*/ + + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 + + Creates a backend object. This way the platform can decide the backend preference. +*/ + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 + + Using the library loader of the platform, loads a given backend provided the + specified \a library and \a version. +*/ + +/*! + \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 + + Tries to check whether the default backend supports the MIME type specified by \a mimeType + without loading the actual backend library. + \omit + On KDE this reads the MIME type list from the .desktop file of + the backend. + \endomit +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 + + Saves the volume for the given output. +*/ + +/*! + \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 + + Loads the volume for the given output. +*/ + +/*! + \class Phonon::MediaNode + \inmodule Phonon + \inheaderfile Phonon/MediaNode + \since 4.4 + \brief The MediaNode class is the base class for all nodes in a media graph. + + In all phonon applications, one builds a media graph consisting of + MediaNodes. The graph will take multimedia content, e.g., from a + file, as input. After its nodes have processed the multimedia, the + graph will output the media again, e.g., to a sound card. + + The multimedia content is streamed over \l{Phonon::}{Path}s + between the nodes in the graph. You can query the paths that are + connected to a media node with inputPaths() and outputPaths(). + + You can check whether the node is implemented by the current + backend by calling isValid(). This does not guarantee that an + instance of the class works as expected, but that the backend has + implemented functionality for the class. + + Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. + Please refer to their class descriptions for details about their usage, and to + find out which nodes can be connected to each other. See also \l{Building + Graphs} in Phonon's \l{Phonon Overview}{overview} document. + + Two nodes are connected to each other using the + Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} + functions (only \l{Phonon::Effect}s use + \l{Phonon::Path::}{insertEffect()}). We show a code example below, + in which we build a media graph for video playback and then query + its media nodes for their \l{Phonon::}{Path}s: + + \snippet doc/src/snippets/medianodesnippet.cpp 0 + + When you create a Phonon application, you will likely build the + graph yourself. This makes isValid() the most useful function of + this class. The other two functions help navigate the graph, which + you do not need to do as you created the nodes yourself. + + \sa {Phonon Overview}, Phonon::MediaObject, + Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn virtual Phonon::MediaNode::~MediaNode() + + Destroys the media node and any paths connecting it to other + nodes. Any \l{Phonon::}{Effect}s connected to these paths will + also be deleted. +*/ + +/*! + \fn bool Phonon::MediaNode::isValid() const + + Returns true if the backend provides an implementation of this + class; otherwise returns false. + + This does not guarantee that instances of the class works as + expected, but that the backend has implemented the functionality + for this class. For instance, Qt's GStreamer backend will return + true for instances of the \l{Phonon::}{AudioOutput} class, even if + there is a problem with GStreamer and it could not play sound. + +*/ + +/*! + \fn QList Phonon::MediaNode::inputPaths() const + + Returns the paths that inputs multimedia to this media node. + + \sa outputPaths() +*/ + +/*! + \fn QList Phonon::MediaNode::outputPaths() const + + Returns the paths to which this media node outputs media. + + \sa inputPaths() +*/ + +/*! + \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) + \internal +*/ + +/*! + \class Phonon::GlobalConfig + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::GlobalConfig() + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::~GlobalConfig() + \internal +*/ + +/*! + \fn QList Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const + \internal +*/ + +/*! + \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const + \internal +*/ + +/*! + \class Phonon::ObjectDescriptionData + \inmodule Phonon + \since 4.4 + \internal + \brief Data class for objects describing devices or features of the backend. + + \sa Phonon::BackendCapabilities +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + as \a otherDescription; otherwise returns \c false. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::name() const + + Returns the name of the capture source. + + \return A string that should be presented to the user to + choose the capture source. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::description() const + + Returns a description of the capture source. This text should + make clear what sound source this is, which is sometimes hard + to describe or understand from just the name. + + \return A string describing the capture source. +*/ + +/*! + \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const + + Returns a named property. + + If the property is not set an invalid value is returned. + + \sa propertyNames() +*/ + +/*! + \fn QList Phonon::ObjectDescriptionData::propertyNames() const + + Returns all names that return valid data when property() is called. + + \sa property() +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::isValid() const + + Returns true if the Tuple is valid (index != -1); otherwise returns + false. +*/ + +/*! + \fn int Phonon::ObjectDescriptionData::index() const + + A unique identifier for this device/. Used internally + to distinguish between the devices/. + + \return An integer that uniquely identifies every device. +*/ + +/*! + \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) + \internal +*/ + +/*! + \class Phonon::AddonInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for Menu, Chapter, Angle and Title/Track control. +*/ + +/*! + \fn virtual Phonon::AddonInterface::~AddonInterface() + \internal +*/ + +/*! + \enum Phonon::AddonInterface::Interface + + This enum describes the type of interface represented by an AddonInterface object. + + \value NavigationInterface + \value ChapterInterface + \value AngleInterface + \value TitleInterface +*/ + +/*! + \enum Phonon::AddonInterface::NavigationCommand + \internal + \value Menu1Button +*/ + +/*! + \enum Phonon::AddonInterface::ChapterCommand + \internal + \value availableChapters + \value chapter + \value setChapter +*/ + +/*! + \enum Phonon::AddonInterface::AngleCommand + \internal + \value availableAngles + \value angle + \value setAngle +*/ + +/*! + \enum Phonon::AddonInterface::TitleCommand + \internal + \value availableTitles + \value title + \value setTitle + \value autoplayTitles + \value setAutoplayTitles +*/ + +/*! + \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 + \internal +*/ + +/*! + \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, + const QList &arguments) = 0 + \internal +*/ + +/*! + \class Phonon::MediaNodePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::Factory + \inmodule Phonon + \internal +*/ + +/*! + \fn Sender *Phonon::Factory::sender() + + Returns a pointer to the object emitting the signals. + + \sa Sender::backendChanged() +*/ + +/*! + \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) + + Create a new backend object for a MediaObject. + + \return a pointer to the MediaObject the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) + + Create a new backend object for a Effect. + + \return a pointer to the Effect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) + + Create a new backend object for a VolumeFaderEffect. + + \return a pointer to the VolumeFaderEffect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) + + Create a new backend object for a AudioOutput. + + \return a pointer to the AudioOutput the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) + + Create a new backend object for a VideoWidget. + + \return a pointer to the VideoWidget the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) + + \return a pointer to the backend interface. +*/ + +/*! + \fn QString Phonon::Factory::identifier() + + Unique identifier for the Backend. Can be used in configuration files + for example. +*/ + + +/*! + \fn QString Phonon::Factory::backendName() + + Get the name of the Backend. + \omit + It's the name from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendComment() + + Get the comment of the Backend. + \omit + It's the comment from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendVersion() + + Get the version of the Backend. + \omit + It's the version from the .desktop file. + \endomit + + The version is especially interesting if there are several versions + available for binary incompatible versions of the backend's media + framework. +*/ + +/*! + \fn QString Phonon::Factory::backendIcon() + + Get the icon (name) of the Backend. + \omit + It's the icon from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendWebsite() + + Get the website of the Backend. + \omit + It's the website from the .desktop file. + \endomit +*/ + +/*! + \fn QObject *Phonon::Factory::registerQObject(QObject *object) + + Registers the given backend \a object with the factory. +*/ + +/*! + \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) +*/ + +/*! + \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::setBackend(QObject *) +*/ + +/*! + \fn PlatformPlugin *Phonon::Factory::platformPlugin() +*/ + +/*! +/*! + \class Phonon::AbstractMediaStreamPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::FrontendInterfacePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::IODeviceStream + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) + \internal + + Creates a new IODeviceStream with the given \a ioDevice and \a + parent. + +*/ + +/*! + \fn Phonon::IODeviceStream::~IODeviceStream() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::reset() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::needData() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::seekStream(qint64) + \internal +*/ + +/*! + \namespace Phonon::Platform + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::EffectDescriptionModel + \inmodule Phonon + \brief provides a item view model containing available audio effects. + +*/ + +/*! + \typedef Phonon::SubtitleDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::SubtitleDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDevice + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDeviceModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::CleanUpFunction + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::QObjectPair + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \typedef Phonon::AudioOutputDeviceModel + \inmodule Phonon + \brief provides an item view model containing available audio output devices. + +*/ + +/*! + \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) + \internal + +*/ + +/*! + \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() + \internal +*/ + +/*! + \class Phonon::ConstIface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::CleanUpGlobalStatic + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameterPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::QSettingsGroup + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::MediaNodeDestructionHandler + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() + \internal + Called from Base::~Base if this object was registered + using BasePrivate::addDestructionHandler(). +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) + \internal +*/ + +/*! + \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) + \internal + + Constructs a new EffectWidget for the specified \a effect and with + the specified \a parent. +*/ + +/*! + \fn Phonon::EffectWidget::~EffectWidget() + \internal +*/ + +/*! + \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription &o) + \internal +*/ + +/*! + \class Phonon::ListModelHelper + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputInterface42 + \inmodule Phonon + \since 4.4 + \internal +*/ + diff --git a/doc/src/classes/q3asciicache.qdoc b/doc/src/classes/q3asciicache.qdoc new file mode 100644 index 0000000..43537cc --- /dev/null +++ b/doc/src/classes/q3asciicache.qdoc @@ -0,0 +1,465 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiCache + \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. + \compat + + Q3AsciiCache is implemented as a template class. Define a template + instance Q3AsciiCache\ to create a cache that operates on + pointers to X (X*). + + A cache is a least recently used (LRU) list of cache items. The + cache items are accessed via \c char* keys. For Unicode keys use + the Q3Cache template instead, which uses QString keys. A Q3Cache + has the same performace as a Q3AsciiCache. + + Each cache item has a cost. The sum of item costs, totalCost(), + will not exceed the maximum cache cost, maxCost(). If inserting a + new item would cause the total cost to exceed the maximum cost, + the least recently used items in the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink tells the cache to delete items that + are removed. The default is to not delete items when then are + removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item the virtual function + Q3PtrCollection::deleteItem() is called. Its default implementation + in Q3AsciiCache is to delete the item if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + There is a Q3AsciiCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache +*/ + +/*! + \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison only affects the 26 letters in + US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes + a copy of the cache keys, otherwise it copies just the const char + * pointer - slightly faster if you can guarantee that the keys + will never change, but very risky. +*/ + +/*! + \fn Q3AsciiCache::~Q3AsciiCache() + + Removes all items from the cache and destroys it. + All iterators that access this cache will be reset. +*/ + +/*! + \fn Q3AsciiCache& Q3AsciiCache::operator=( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3AsciiCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3AsciiCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3AsciiCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3AsciiCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() size() +*/ + +/*! + \fn uint Q3AsciiCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3AsciiCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) + + Inserts the item \a d into the cache using key \a k, and with an + associated cost of \a c. Returns TRUE if the item is successfully + inserted. Returns FALSE if the item is not inserted, for example, + if the cost of the item exceeds maxCost(). + + The cache's size is limited, and if the total cost is too high, + Q3AsciiCache will remove old, least recently used items until there + is room for this new item. + + Items with duplicate keys can be inserted. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE, you must delete \a d + yourself. Additionally, be very careful about using \a d after + calling this function, because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3AsciiCache::remove( const char *k ) + + Removes the item with key \a k and returns TRUE if the item was + present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink. + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3AsciiCache::take( const char *k ) + + Takes the item associated with \a k out of the cache without + deleting it and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3AsciiCache::clear() + + Removes all items from the cache, and deletes them if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been + enabled. + + All cache iterators that operate on this cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3AsciiCache::find( const char *k, bool ref ) const + + Returns the item with key \a k, or 0 if the key does not exist + in the cache. If \a ref is TRUE (the default), the item is moved + to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3AsciiCache::operator[]( const char *k ) const + + Returns the item with key \a k, or 0 if \a k does not exist in + the cache, and moves the item to the front of the least recently + used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3AsciiCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3AsciiCacheIterator + \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators + that refer an item when that item is removed. + + Q3AsciiCacheIterator provides an operator++() and an operator+=() + to traverse the cache; current() and currentKey() to access the + current cache item and its key. It also provides atFirst() and + atLast(), which return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty; and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3AsciiCache +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current() but moves + independently from there on. +*/ + +/*! + \fn Q3AsciiCacheIterator& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3AsciiCacheIterator::count() const + + Returns the number of items in the cache over which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3AsciiCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 + if it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes that the new current item for the iterator. If + current() was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/classes/q3asciidict.qdoc b/doc/src/classes/q3asciidict.qdoc new file mode 100644 index 0000000..9a51db1 --- /dev/null +++ b/doc/src/classes/q3asciidict.qdoc @@ -0,0 +1,416 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiDict + \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. + \compat + + Q3AsciiDict is implemented as a template class. Define a template + instance Q3AsciiDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + char* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template + instead, which uses QString keys. A Q3Dict has the same + performace as a Q3AsciiDict. + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 + In this example we use a dictionary to keep track of the line + edits we're using. We insert each line edit into the dictionary + with a unique name and then access the line edits via the + dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number (a + bit larger than the expected number of entries). This makes the + hash distribution better and will improve lookup performance. + + When \a caseSensitive is TRUE (the default) Q3AsciiDict treats + "abc" and "Abc" as different keys; when it is FALSE "abc" and + "Abc" are the same. Case-insensitive comparison only considers the + 26 letters in US-ASCII. + + If \a copyKeys is TRUE (the default), the dictionary copies keys + using strcpy(); if it is FALSE, the dictionary just copies the + pointers. +*/ + +/*! + \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3AsciiDict::~Q3AsciiDict() + + Removes all items from the dictionary and destroys it. + + The items are deleted if auto-delete is enabled. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3AsciiDict &Q3AsciiDict::operator=(const Q3AsciiDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy) unless newItem() has been reimplemented(). +*/ + +/*! + \fn uint Q3AsciiDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3AsciiDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3AsciiDict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise it returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::insert( const char *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3AsciiDict::replace( const char *key, const type *item ) + + Replaces an item that has a key equal to \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3AsciiDict::remove( const char *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the key existed in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::take( const char *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3AsciiDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::find( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3AsciiDict::operator[]( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does + not exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3AsciiDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3AsciiDict::read( QDataStream &s, + Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3AsciiDictIterator + \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. + \compat + + Q3AsciiDictIterator is implemented as a template class. Define a + template instance Q3AsciiDictIterator\ to create a dictionary + iterator that operates on Q3AsciiDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 + In the example we insert some line edits into a dictionary, then + iterate over the dictionary printing the strings associated with + those line edits. + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. + + Multiple iterators may independently traverse the same dictionary. + A Q3AsciiDict knows about all the iterators that are operating on + the dictionary. When an item is removed from the dictionary, + Q3AsciiDict updates all the iterators that are referring to the + removed item to point to the next item in the (arbitrary) + traversal order. + + \sa Q3AsciiDict +*/ + +/*! + \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3AsciiDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0, + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3AsciiDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3AsciiDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiDictIterator::currentKey() const + + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3cache.qdoc b/doc/src/classes/q3cache.qdoc new file mode 100644 index 0000000..d8799b6 --- /dev/null +++ b/doc/src/classes/q3cache.qdoc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Cache + \brief The Q3Cache class is a template class that provides a cache based on QString keys. + \compat + + A cache is a least recently used (LRU) list of cache items. Each + cache item has a key and a certain cost. The sum of item costs, + totalCost(), never exceeds the maximum cache cost, maxCost(). If + inserting a new item would cause the total cost to exceed the + maximum cost, the least recently used items in the cache are + removed. + + Q3Cache is a template class. Q3Cache\ defines a cache that + operates on pointers to X, or X*. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item, the virtual function + Q3PtrCollection::deleteItem() is called. The default + implementation deletes the item if auto-deletion is enabled, and + does nothing otherwise. + + There is a Q3CacheIterator that can be used to traverse the items + in the cache in arbitrary order. + + In Q3Cache, the cache items are accessed via QString keys, which + are Unicode strings. If you want to use non-Unicode, plain 8-bit + \c char* keys, use the Q3AsciiCache template. A Q3Cache has the + same performance as a Q3AsciiCache. + + \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache +*/ + +/*! + \fn Q3Cache::Q3Cache( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it a prime number and at least 50% bigger + than the largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison considers all Unicode letters. +*/ + +/*! + \fn Q3Cache::~Q3Cache() + + Removes all items from the cache and destroys it. All iterators + that access this cache will be reset. +*/ + +/*! + \fn Q3Cache& Q3Cache::operator=( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3Cache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3Cache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3Cache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are deleted + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3Cache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3Cache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3Cache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and associated + cost, \a c. Returns TRUE if it is successfully inserted; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3Cache will remove old, least recently used items until there is + room for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (which could happen, e.g. + if the cost of this item alone exceeds maxCost()) you must delete + \a d yourself. Additionally, be very careful about using \a d + after calling this function because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3Cache::remove( const QString &k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3Cache::take( const QString &k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3Cache::clear() + + Removes all items from the cache and deletes them if auto-deletion + has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3Cache::find( const QString &k, bool ref ) const + + Returns the item associated with key \a k, or 0 if the key does + not exist in the cache. If \a ref is TRUE (the default), the item + is moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3Cache::operator[]( const QString &k ) const + + Returns the item associated with key \a k, or 0 if \a k does not + exist in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3Cache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/***************************************************************************** + Q3CacheIterator documentation + *****************************************************************************/ + +/*! + \class Q3CacheIterator qcache.h + \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3Cache. Q3Cache updates all iterators that + refer an item when that item is removed. + + Q3CacheIterator provides an operator++(), and an operator+=() to + traverse the cache. The current() and currentKey() functions are + used to access the current cache item and its key. The atFirst() + and atLast() return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty, and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3Cache +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3CacheIterator& Q3CacheIterator::operator=( const Q3CacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3CacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3CacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + it returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3CacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3CacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3CacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3CacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3CacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3CacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn QString Q3CacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3CacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3CacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator++() + + Prefix++ makes the iterator point to the item just after current() + and makes that the new current item for the iterator. If current() + was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3CacheIterator::operator--() + + Prefix-- makes the iterator point to the item just before + current() and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/classes/q3dict.qdoc b/doc/src/classes/q3dict.qdoc new file mode 100644 index 0000000..0e6d51d --- /dev/null +++ b/doc/src/classes/q3dict.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Dict + \brief The Q3Dict class is a template class that provides a + dictionary based on QString keys. + \compat + + Q3Dict is implemented as a template class. Define a template + instance Q3Dict\ to create a dictionary that operates on + pointers to X (X *). + + A dictionary is a collection of key-value pairs. The key is a + QString used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + If you want to use non-Unicode, plain 8-bit \c char* keys, use the + Q3AsciiDict template. A Q3Dict has the same performance as a + Q3AsciiDict. If you want to have a dictionary that maps QStrings to + QStrings use QMap. + + The size() of the dictionary is very important. In order to get + good performance, you should use a suitably large prime number. + Suitable means equal to or larger than the maximum expected number + of dictionary items. Size is set in the constructor but may be + changed with resize(). + + Items are inserted with insert(); 0 pointers cannot be inserted. + Items are removed with remove(). All the items in a dictionary can + be removed with clear(). The number of items in the dictionary is + returned by count(). If the dictionary contains no items isEmpty() + returns TRUE. You can change an item's value with replace(). Items + are looked up with operator[](), or with find() which return a + pointer to the value or 0 if the given key does not exist. You can + take an item out of the dictionary with take(). + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete + items that are removed. The default behavior is not to delete + items when they are removed. + + When an item is inserted, the key is converted (hashed) to an + integer index into an internal hash array. This makes lookup very + fast. + + Items with equal keys are allowed. When inserting two items with + the same key, only the last inserted item will be accessible (last + in, first out) until it is removed. + + The Q3DictIterator class can traverse the dictionary, but only in + an arbitrary order. Multiple iterators may independently traverse + the same dictionary. + + When inserting an item into a dictionary, only the pointer is + copied, not the item itself, i.e. a shallow copy is made. It is + possible to make the dictionary copy all of the item's data (a + deep copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a dictionary item, the virtual function + Q3PtrCollection::deleteItem() is called. Q3Dict's default + implementation is to delete the item if auto-deletion is enabled. + + \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number + (e.g. a prime that's slightly larger than the expected number of + entries). This makes the hash distribution better which will lead + to faster lookup. + + If \a caseSensitive is TRUE (the default), keys which differ only + by case are considered different. +*/ + +/*! + \fn Q3Dict::Q3Dict( const Q3Dict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3Dict::~Q3Dict() + + Removes all items from the dictionary and destroys it. If + setAutoDelete() is TRUE, each value is deleted. All iterators that + access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3Dict &Q3Dict::operator=(const Q3Dict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3Dict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3Dict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3Dict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3Dict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3Dict::insert( const QString &key, const type *item ) + + Inserts the key \a key with value \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3Dict::replace( const QString &key, const type *item ) + + Replaces the value of the key, \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 + + If there are two or more items with equal keys, then the last item + that was inserted will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3Dict::remove( const QString &key ) + + Removes the item with \a key from the dictionary. Returns TRUE if + successful, i.e. if the item is in the dictionary; otherwise + returns FALSE. + + If there are two or more items with equal keys, then the last item + that was inserted will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::take( const QString &key ) + + Takes the item with \a key out of the dictionary without deleting + it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last item + that was inserted will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3Dict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on the dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::find( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not exist + in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3Dict::operator[]( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3Dict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3DictIterator + \brief The Q3DictIterator class provides an iterator for Q3Dict collections. + \compat + + Q3DictIterator is implemented as a template class. Define a + template instance Q3DictIterator\ to create a dictionary + iterator that operates on Q3Dict\ (dictionary of X*). + + The traversal order is arbitrary; when we speak of the "first", + "last" and "next" item we are talking in terms of this arbitrary + order. + + Multiple iterators may independently traverse the same dictionary. + A Q3Dict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3Dict + updates all iterators that are referring to the removed item to + point to the next item in the (arbitrary) traversal order. + + Example: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 + In the example we insert some pointers to line edits into a + dictionary, then iterate over the dictionary printing the strings + associated with the line edits. + + \sa Q3Dict +*/ + +/*! + \fn Q3DictIterator::Q3DictIterator( const Q3Dict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the first item in the dictionary, \a dict. First + in this context means first in the arbitrary traversal order. +*/ + +/*! + \fn Q3DictIterator::~Q3DictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3DictIterator::count() const + + Returns the number of items in the dictionary over which the + iterator is operating. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3DictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3DictIterator::toFirst() + + Resets the iterator, making the first item the first current item. + First in this context means first in the arbitrary traversal + order. Returns a pointer to this item. + + If the dictionary is empty it sets the current item to 0 and + returns 0. +*/ + +/*! + \fn type *Q3DictIterator::operator*() + \internal +*/ + +/*! + \fn Q3DictIterator::operator type*() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + + +/*! + \fn type *Q3DictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn QString Q3DictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3DictIterator::operator()() + + Makes the next item current and returns the original current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator++() + + Prefix ++ makes the next item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator+=( uint jump ) + \internal + Sets the current item to the item \a jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3intcache.qdoc b/doc/src/classes/q3intcache.qdoc new file mode 100644 index 0000000..dfff679 --- /dev/null +++ b/doc/src/classes/q3intcache.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntCache + \brief The Q3IntCache class is a template class that provides a cache based on long keys. + \compat + + Q3IntCache is implemented as a template class. Define a template + instance Q3IntCache\ to create a cache that operates on + pointers to X, or X*. + + A cache is a least recently used (LRU) list of cache items, + accessed via \c long keys. Each cache item has a cost. The sum + of item costs, totalCost(), will not exceed the maximum cache + cost, maxCost(). If inserting a new item would cause the total + cost to exceed the maximum cost, the least recently used items in + the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e. remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a cache item, the item will be automatically + deleted if auto-deletion is enabled. + + There is a Q3IntCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache +*/ + +/*! + \fn Q3IntCache::Q3IntCache( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn Q3IntCache::Q3IntCache( int maxCost, int size ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item is associated with a cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. +*/ + +/*! + \fn Q3IntCache::~Q3IntCache() + + Removes all items from the cache and then destroys the int cache. + If auto-deletion is enabled the cache's items are deleted. All + iterators that access this cache will be reset. +*/ + +/*! + \fn Q3IntCache& Q3IntCache::operator=( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3IntCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3IntCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3IntCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3IntCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3IntCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit larger than count() is likely to be. +*/ + +/*! + \fn bool Q3IntCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and assigns it + a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3IntCache will remove old, least-used items until there is room + for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (for example, the cost \c, + exceeds maxCost()), you must delete \a d yourself. Additionally, + be very careful about using \a d after calling this function. Any + other insertions into the cache, from anywhere in the application + or within Qt itself, could cause the object to be discarded from + the cache and the pointer to become invalid. +*/ + +/*! + \fn bool Q3IntCache::remove( long k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e. if you + have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted most recently is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type * Q3IntCache::take( long k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out or 0 if + the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted most recently is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3IntCache::clear() + + Removes all items from the cache, and deletes them if + auto-deletion has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type * Q3IntCache::find( long k, bool ref ) const + + Returns the item associated with \a k, or 0 if the key does not + exist in the cache. If \a ref is TRUE (the default), the item is + moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. +*/ + +/*! + \fn type * Q3IntCache::operator[]( long k ) const + + Returns the item associated with \a k, or 0 if \a k does not exist + in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3IntCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3IntCacheIterator + \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3IntCache. Q3IntCache updates all iterators + that refer an item when that item is removed. + + Q3IntCacheIterator provides an operator++(), and an operator+=() to + traverse the cache; current() and currentKey() to access the + current cache item and its key; atFirst() atLast(), which return + TRUE if the iterator points to the first/last item in the cache; + isEmpty(), which returns TRUE if the cache is empty; and count(), + which returns the number of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3IntCache +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache (or rather, the + first item is defined to be the item at which this constructor + sets the iterator to point). +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3IntCacheIterator& Q3IntCacheIterator::operator=( const Q3IntCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3IntCacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3IntCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3IntCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3IntCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3IntCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3IntCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes it the new current item for the iterator. If + current() was the last item, operator--() returns 0. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes it the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ diff --git a/doc/src/classes/q3intdict.qdoc b/doc/src/classes/q3intdict.qdoc new file mode 100644 index 0000000..cef2e79 --- /dev/null +++ b/doc/src/classes/q3intdict.qdoc @@ -0,0 +1,390 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntDict + \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ + \compat + + Q3IntDict is implemented as a template class. Define a template + instance Q3IntDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is an \c + long used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict +*/ + + +/*! + \fn Q3IntDict::Q3IntDict( int size ) + + Constructs a dictionary using an internal hash array of size \a + size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better which leads to faster lookup. +*/ + +/*! + \fn Q3IntDict::Q3IntDict( const Q3IntDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3IntDict::~Q3IntDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3IntDict &Q3IntDict::operator=(const Q3IntDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3IntDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3IntDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3IntDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3IntDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3IntDict::insert( long key, const type *item ) + + Insert item \a item into the dictionary using key \a key. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3IntDict::replace( long key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3IntDict::remove( long key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the \a key is in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal + order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::take( long key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary's traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3IntDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::find( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3IntDict::operator[]( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3IntDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3IntDictIterator + \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. + \compat + + Q3IntDictIterator is implemented as a template class. Define a + template instance Q3IntDictIterator\ to create a dictionary + iterator that operates on Q3IntDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 + + Note that the traversal order is arbitrary; you are not guaranteed the + order shown above. + + Multiple iterators may independently traverse the same dictionary. + A Q3IntDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3IntDict + updates all iterators that refer the removed item to point to the + next item in the traversal order. + + \sa Q3IntDict +*/ + +/*! + \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the 'first' item in the \a dict. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. +*/ + +/*! + \fn Q3IntDictIterator::~Q3IntDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3IntDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise eturns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3IntDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. If the dictionary is empty it sets the current item to + 0 and returns 0. +*/ + +/*! + \fn Q3IntDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntDictIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3memarray.qdoc b/doc/src/classes/q3memarray.qdoc new file mode 100644 index 0000000..b9c1f73 --- /dev/null +++ b/doc/src/classes/q3memarray.qdoc @@ -0,0 +1,523 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3MemArray + \brief The Q3MemArray class is a template class that provides arrays of simple types. + \compat + + Q3MemArray is implemented as a template class. Define a template + instance Q3MemArray\ to create an array that contains X items. + + Q3MemArray stores the array elements directly in the array. It can + only deal with simple types (i.e. C++ types, structs, and classes + that have no constructors, destructors, or virtual functions). + Q3MemArray uses bitwise operations to copy and compare array + elements. + + The Q3PtrVector collection class is also a kind of array. Like most + old Qt collection classes, it uses pointers to the contained items. + + Q3MemArray uses explicit sharing with a + reference count. If more than one array shares common data and one + of the arrays is modified, all the arrays are modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in lower memory use + and less copying of data. + + Example: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 + + Note concerning the use of Q3MemArray for manipulating structs or + classes: Compilers will often pad the size of structs of odd sizes + up to the nearest word boundary. This will then be the size + Q3MemArray will use for its bitwise element comparisons. Because + the remaining bytes will typically be uninitialized, this can + cause find() etc. to fail to find the element. Example: + + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 + + To work around this, make sure that you use a struct where + sizeof() returns the same as the sum of the sizes of the members + either by changing the types of the struct members or by adding + dummy members. + + Q3MemArray data can be traversed by iterators (see begin() and + end()). The number of items is returned by count(). The array can + be resized with resize() and filled using fill(). + + You can make a shallow copy of the array with assign() (or + operator=()) and a deep copy with duplicate(). + + Search for values in the array with find() and contains(). For + sorted arrays (see sort()) you can search using bsearch(). + + You can set the data directly using setRawData() and + resetRawData(), although this requires care. +*/ + +/*! \fn Q3MemArray::operator QVector() const + + Automatically converts the Q3MemArray into a QVector. +*/ + +/*! \typedef Q3MemArray::Iterator + A Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ConstIterator + A const Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ValueType + \internal +*/ + +/*! + \fn Q3MemArray::Q3MemArray() + + Constructs a null array. + + \sa isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( int size ) + + Constructs an array with room for \a size elements. Makes a null + array if \a size == 0. + + The elements are left uninitialized. + + \sa resize(), isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( const Q3MemArray &a ) + + Constructs a shallow copy of \a a. + + \sa assign() +*/ + +/*! + \fn Q3MemArray::Q3MemArray(const QVector &vector) + + Constructs a copy of \a vector. +*/ + +/*! + \fn Q3MemArray::Q3MemArray(int arg1, int arg2) + + Constructs an array \e{without allocating} array space. The + arguments \a arg1 and \a arg2 should be zero. Use at your own + risk. +*/ + +/*! + \fn Q3MemArray::~Q3MemArray() + + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::operator=( const Q3MemArray &a ) + + Assigns a shallow copy of \a a to this array and returns a + reference to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *Q3MemArray::data() const + + Returns a pointer to the actual array data. + + The array is a null array if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3MemArray::nrefs() const + + Returns the reference count for the shared array data. This + reference count is always greater than zero. +*/ + +/*! + \fn uint Q3MemArray::size() const + + Returns the size of the array (maximum number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint Q3MemArray::count() const + + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::isEmpty() const + + Returns TRUE if the array is empty; otherwise returns FALSE. + + isEmpty() is equivalent to isNull() for Q3MemArray (unlike + QString). +*/ + +/*! + \fn bool Q3MemArray::isNull() const + + Returns TRUE if the array is null; otherwise returns FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool Q3MemArray::resize( uint size, Optimization optim ) + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be + allocated. + + New elements are not initialized. + + \a optim is either Q3GArray::MemOptim (the default) or + Q3GArray::SpeedOptim. When optimizing for speed rather than memory + consumption, the array uses a smart grow and shrink algorithm that + might allocate more memory than is actually needed for \a size + elements. This speeds up subsequent resize operations, for example + when appending many elements to an array, since the space has + already been allocated. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::resize( uint size ) + + \overload + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + New elements are not initialized. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::truncate( uint pos ) + + Truncates the array at position \a pos. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + Equivalent to resize(\a pos). + + \sa resize() +*/ + +/*! + \fn bool Q3MemArray::fill( const type &v, int size ) + + Fills the array with the value \a v. If \a size is specified as + different from -1, then the array will be resized before being + filled. + + Returns TRUE if successful, i.e. if \a size is -1, or \a size is + != -1 and the memory can be allocated; otherwise returns FALSE. + + \sa resize() +*/ + +/*! + \fn void Q3MemArray::detach() + + Detaches this array from shared array data; i.e. it makes a + private, deep copy of the data. + + Copying will be performed only if the \link nrefs() reference + count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn Q3MemArray Q3MemArray::copy() const + + Returns a deep copy of this array. + + \sa detach(), duplicate() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const Q3MemArray &a ) + + Shallow copy. Dereferences the current array and references the + data contained in \a a instead. Returns a reference to this array. + + \sa operator=() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const type *data, uint size ) + + \overload + + Shallow copy. Dereferences the current array and references the + array data \a data, which contains \a size elements. Returns a + reference to this array. + + Do not delete \a data later; Q3MemArray will call free() on it + at the right time. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const Q3MemArray &a ) + + Deep copy. Dereferences the current array and obtains a copy of + the data contained in \a a instead. Returns a reference to this + array. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const type *data, uint size ) + + \overload + + Deep copy. Dereferences the current array and obtains a copy of + the array data \a data instead. Returns a reference to this array. + The size of the array is given by \a size. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::setRawData( const type *data, uint size ) + + Sets raw data and returns a reference to the array. + + Dereferences the current array and sets the new array data to \a + data and the new array size to \a size. Do not attempt to resize + or re-assign the array data when raw data has been set. Call + resetRawData(\a data, \a size) to reset the array. + + Setting raw data is useful because it sets Q3MemArray data without + allocating memory or copying data. + + Example I (intended use): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 + + Example II (you don't want to do this): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 + + \warning If you do not call resetRawData(), Q3MemArray will attempt + to deallocate or reallocate the raw data, which might not be too + good. Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void Q3MemArray::resetRawData( const type *data, uint size ) + + Removes internal references to the raw data that was set using + setRawData(). This means that Q3MemArray no longer has access to + the \a data, so you are free to manipulate \a data as you wish. + You can now use the Q3MemArray without affecting the original \a + data, for example by calling setRawData() with a pointer to some + other data. + + The arguments must be the \a data and length, \a size, that were + passed to setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int Q3MemArray::find( const type &v, uint index ) const + + Finds the first occurrence of \a v, starting at position \a index. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa contains() +*/ + +/*! + \fn int Q3MemArray::contains( const type &v ) const + + Returns the number of times \a v occurs in the array. + + \sa find() +*/ + +/*! + \fn void Q3MemArray::sort() + + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int Q3MemArray::bsearch( const type &v ) const + + In a sorted array (as sorted by sort()), finds the first + occurrence of \a v by using a binary search. For a sorted + array this is generally much faster than find(), which does + a linear search. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &Q3MemArray::operator[]( int index ) const + + Returns a reference to the element at position \a index in the + array. + + This can be used to both read and set an element. Equivalent to + at(). + + \sa at() +*/ + +/*! + \fn type &Q3MemArray::at( uint index ) const + + Returns a reference to the element at position \a index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn Q3MemArray::operator const type *() const + + Cast operator. Returns a pointer to the array. + + \sa data() +*/ + +/*! + \fn bool Q3MemArray::operator==( const Q3MemArray &a ) const + + Returns TRUE if this array is equal to \a a; otherwise returns + FALSE. + + The two arrays are compared bitwise. + + \sa operator!=() +*/ + +/*! + \fn bool Q3MemArray::operator!=( const Q3MemArray &a ) const + + Returns TRUE if this array is different from \a a; otherwise + returns FALSE. + + The two arrays are compared bitwise. + + \sa operator==() +*/ + +/*! + \fn Iterator Q3MemArray::begin() + + Returns an iterator pointing at the beginning of this array. This + iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn Iterator Q3MemArray::end() + + Returns an iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::begin() const + + \overload + + Returns a const iterator pointing at the beginning of this array. + This iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::end() const + + \overload + + Returns a const iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ diff --git a/doc/src/classes/q3popupmenu.qdoc b/doc/src/classes/q3popupmenu.qdoc new file mode 100644 index 0000000..a2cfe08 --- /dev/null +++ b/doc/src/classes/q3popupmenu.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PopupMenu + \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. + \compat + + Use QMenu in new applications. Note that the menu's actions must + be \l {Q3Action}s. +*/ + +/*! + \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) + + Constructs a menu with the given \a parent and \a name. +*/ + +/*! + \fn int Q3PopupMenu::exec() + + Pops up the menu and returns the ID of the action that was + selected. + + \sa QMenu::exec() +*/ + +/*! + \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) + + Pops up the menu at coordinate \a pos and returns the ID of the + action that was selected. + + If \a indexAtPoint is specified, the menu will pop up with the + item at index \a indexAtPoint under the mouse cursor. + + \sa QMenu::exec() +*/ diff --git a/doc/src/classes/q3ptrdict.qdoc b/doc/src/classes/q3ptrdict.qdoc new file mode 100644 index 0000000..38ca0bb --- /dev/null +++ b/doc/src/classes/q3ptrdict.qdoc @@ -0,0 +1,388 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrDict + \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. + \compat + + Q3PtrDict is implemented as a template class. Define a template + instance Q3PtrDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + void* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 + In this example we use a dictionary to add an extra property (a + char*) to the line edits we're using. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict +*/ + + +/*! + \fn Q3PtrDict::Q3PtrDict( int size ) + + Constructs a dictionary using an internal hash array with the size + \a size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better and improves lookup performance. +*/ + +/*! + \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrDict::~Q3PtrDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrDict &Q3PtrDict::operator=(const Q3PtrDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into the dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3PtrDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3PtrDict::size() const + + Returns the size of the internal hash table (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3PtrDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::insert( void *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3PtrDict::replace( void *key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3PtrDict::remove( void *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if \a key is in the dictionary; + otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::take( void *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3PtrDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be + reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::find( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3PtrDict::operator[]( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3PtrDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3PtrDictIterator + \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. + \compat + + Q3PtrDictIterator is implemented as a template class. Define a + template instance Q3PtrDictIterator\ to create a dictionary + iterator that operates on Q3PtrDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 + In the example we insert some line edits into a dictionary, + associating a string with each. We then iterate over the + dictionary printing the associated strings. + + Multiple iterators may independently traverse the same dictionary. + A Q3PtrDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3PtrDict + updates all iterators that refer the removed item to point to the + next item in the traversing order. + + \sa Q3PtrDict +*/ + +/*! + \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3PtrDictIterator::~Q3PtrDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3PtrDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3PtrDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrDictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn void *Q3PtrDictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3ptrlist.qdoc b/doc/src/classes/q3ptrlist.qdoc new file mode 100644 index 0000000..3000940 --- /dev/null +++ b/doc/src/classes/q3ptrlist.qdoc @@ -0,0 +1,1157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrList + \brief The Q3PtrList class is a template class that provides a list. + \compat + + Q3ValueList is an STL-compatible alternative to this class. + + Define a template instance Q3PtrList\ to create a list that + operates on pointers to X (X*). + + The list class is indexable and has a \link at() current + index\endlink and a \link current() current item\endlink. The + first item corresponds to index position 0. The current index is + -1 if the current item is 0. + + Items are inserted with prepend(), insert() or append(). Items are + removed with remove(), removeRef(), removeFirst() and + removeLast(). You can search for an item using find(), findNext(), + findRef() or findNextRef(). The list can be sorted with sort(). + You can count the number of occurrences of an item with contains() + or containsRef(). You can get a pointer to the current item with + current(), to an item at a particular index position in the list + with at() or to the first or last item with getFirst() and + getLast(). You can also iterate over the list with first(), + last(), next() and prev() (which all update current()). The list's + deletion property is set with setAutoDelete(). + + \target example + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 + + Q3PtrList has several member functions for traversing the list, but + using a Q3PtrListIterator can be more practical. Multiple list + iterators may traverse the same list, independently of each other + and of the current list item. + + In the example above we make the call setAutoDelete(true). + Enabling auto-deletion tells the list to delete items that are + removed. The default is to not delete items when they are removed + but this would cause a memory leak in the example because there + are no other references to the list items. + + When inserting an item into a list only the pointer is copied, not + the item itself, i.e. a shallow copy. It is possible to make the + list copy all of the item's data (deep copy) when an item is + inserted. insert(), inSort() and append() call the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a list and reimplement newItem() to have deep copies. + + When removing an item from a list, the virtual function + Q3PtrCollection::deleteItem() is called. Q3PtrList's default + implementation is to delete the item if auto-deletion is enabled. + + The virtual function compareItems() can be reimplemented to + compare two list items. This function is called from all list + functions that need to compare list items, for instance + remove(const type*). If you only want to deal with pointers, there + are functions that compare pointers instead, for instance + removeRef(const type*). These functions are somewhat faster than + those that call compareItems(). + + List items are stored as \c void* in an internal Q3LNode, which + also holds pointers to the next and previous list items. The + functions currentNode(), removeNode(), and takeNode() operate + directly on the Q3LNode, but they should be used with care. The + data component of the node is available through Q3LNode::getData(). + + The Q3StrList class is a list of \c char*. + It reimplements newItem(), deleteItem() and compareItems(). (But + see QStringList for a list of Unicode QStrings.) + + \sa Q3PtrListIterator +*/ + + +/*! + \fn Q3PtrList::Q3PtrList() + + Constructs an empty list. +*/ + +/*! + \fn Q3PtrList::Q3PtrList( const Q3PtrList &list ) + + Constructs a copy of \a list. + + Each item in \a list is \link append() appended\endlink to this + list. Only the pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrList::~Q3PtrList() + + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrList &Q3PtrList::operator=(const Q3PtrList &list) + + Assigns \a list to this list and returns a reference to this list. + + This list is first cleared and then each item in \a list is \link + append() appended\endlink to this list. Only the pointers are + copied (shallow copy) unless newItem() has been reimplemented. +*/ + +/*! + \fn bool Q3PtrList::operator==(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + the same data; otherwise returns FALSE. +*/ + +/*! + \fn uint Q3PtrList::count() const + + Returns the number of items in the list. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrList::operator!=(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + different data; otherwise returns FALSE. +*/ + + +/*! + \fn void Q3PtrList::sort() + + Sorts the list by the result of the virtual compareItems() + function. + + The heap sort algorithm is used for sorting. It sorts n items with + O(n*log n) comparisons. This is the asymptotic optimal solution of + the sorting problem. + + If the items in your list support operator<() and operator==(), + you might be better off with Q3SortedList because it implements the + compareItems() function for you using these two operators. + + \sa inSort() +*/ + +/*! + \fn bool Q3PtrList::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrList::insert( uint index, const type *item ) + + Inserts the \a item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is 0 to count() + (inclusively). The item is appended if \a index == count(). + + The inserted item becomes the current list item. + + \a item must not be 0. + + \sa append(), current(), replace() +*/ + +/*! + \fn bool Q3PtrList::replace( uint index, const type *item ) + + Replaces the item at position \a index with the new \a item. + + Returns TRUE if successful, i.e. \a index is in the range 0 to + count()-1. + + \sa append(), current(), insert() +*/ + +/*! + \fn void Q3PtrList::inSort( const type *item ) + + Inserts the \a item at its sorted position in the list. + + The sort order depends on the virtual compareItems() function. All + items must be inserted with inSort() to maintain the sorting + order. + + The inserted item becomes the current list item. + + \a item must not be 0. + + \warning Using inSort() is slow. An alternative, especially if you + have lots of items, is to simply append() or insert() them and + then use sort(). inSort() takes up to O(n) compares. That means + inserting n items in your list will need O(n^2) compares whereas + sort() only needs O(n*log n) for the same task. So use inSort() + only if you already have a presorted list and want to insert just + a few additional items. + + \sa insert(), compareItems(), current(), sort() +*/ + +/*! + \fn void Q3PtrList::append( const type *item ) + + Inserts the \a item at the end of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( count(), item )}. + + \a item must not be 0. + + \sa insert(), current(), prepend() +*/ + +/*! + \fn void Q3PtrList::prepend( const type *item ) + + Inserts the \a item at the start of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( 0, item )}. + + \a item must not be 0. + + \sa append(), insert(), current() +*/ + +/*! + \fn bool Q3PtrList::remove( uint index ) + + Removes the item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is \c{0..(count() - 1)} + inclusive. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove() + + \overload + + Removes the current list item. + + Returns TRUE if successful, i.e. if the current item isn't 0; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove( const type *item ) + + \overload + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call removeRef(). + + If \a item is NULL then the current item is removed from the list. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), + current() +*/ + +/*! + \fn bool Q3PtrList::removeRef( const type *item ) + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa remove(), clear(), setAutoDelete(), current() +*/ + +/*! + \fn void Q3PtrList::removeNode( Q3LNode *node ) + + Removes the \a node from the list. + + This node must exist in the list, otherwise the program may crash. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list will become the new current list item. + The current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the item succeeding this item or to the preceding item if + the removed item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa takeNode(), currentNode() remove() removeRef() +*/ + +/*! + \fn bool Q3PtrList::removeFirst() + + Removes the first item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeLast(), setAutoDelete(), current() remove() +*/ + +/*! + \fn bool Q3PtrList::removeLast() + + Removes the last item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The last item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeFirst(), setAutoDelete(), current() +*/ + +/*! + \fn type *Q3PtrList::take( uint index ) + + Takes the item at position \a index out of the list without + deleting it (even if \link setAutoDelete() auto-deletion\endlink + is enabled). + + Returns a pointer to the item taken out of the list, or 0 if the + index is out of range. The valid range is \c{0..(count() - 1)} + inclusive. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::take() + + \overload + + Takes the current item out of the list without deleting it (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + + Returns a pointer to the item taken out of the list, or 0 if + the current item is 0. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::takeNode( Q3LNode *node ) + + Takes the \a node out of the list without deleting its item (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list. + + This node must exist in the list, otherwise the program may crash. + + The first item in the list becomes the new current list item. + + All list iterators that refer to the taken item will be set to + point to the item succeeding this item or to the preceding item if + the taken item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), currentNode() +*/ + +/*! + \fn void Q3PtrList::clear() + + Removes all items from the list. + + The removed items are deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + All list iterators that access this list will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn int Q3PtrList::find( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findRef(). + + \sa findNext(), findRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findNext( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findNextRef(). + + \sa find(), findNextRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findRef( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than find() because find() + compares \a item with each list item using compareItems(), whereas + this function only compares the pointers. + + \sa findNextRef(), find(), current() +*/ + +/*! + \fn int Q3PtrList::findNextRef( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than findNext() because + findNext() compares \a item with each list item using + compareItems(), whereas this function only compares the pointers. + + \sa findRef(), findNext(), current() +*/ + +/*! + \fn uint Q3PtrList::contains( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + The compareItems() function is called when looking for the \a item + in the list. If compareItems() is not reimplemented, it is more + efficient to call containsRef(). + + This function does not affect the current list item. + + \sa containsRef(), compareItems() +*/ + +/*! + \fn uint Q3PtrList::containsRef( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + Calling this function is much faster than contains() because + contains() compares \a item with each list item using + compareItems(), whereas his function only compares the pointers. + + This function does not affect the current list item. + + \sa contains() +*/ + +/*! + \fn type *Q3PtrList::at( uint index ) + + Returns a pointer to the item at position \a index in the list, or + 0 if the index is out of range. + + Sets the current list item to this item if \a index is valid. The + valid range is \c{0..(count() - 1)} inclusive. + + This function is very efficient. It starts scanning from the first + item, last item, or current item, whichever is closest to \a + index. + + \sa current() +*/ + +/*! + \fn int Q3PtrList::at() const + + \overload + + Returns the index of the current list item. The returned value is + -1 if the current item is 0. + + \sa current() +*/ + +/*! + \fn type *Q3PtrList::current() const + + Returns a pointer to the current list item. The current item may + be 0 (implies that the current index is -1). + + \sa at() +*/ + +/*! + \fn Q3LNode *Q3PtrList::currentNode() const + + Returns a pointer to the current list node. + + The node can be kept and removed later using removeNode(). The + advantage is that the item can be removed directly without + searching the list. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), takeNode(), current() +*/ + +/*! + \fn type *Q3PtrList::getFirst() const + + Returns a pointer to the first item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa first(), getLast() +*/ + +/*! + \fn type *Q3PtrList::getLast() const + + Returns a pointer to the last item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa last(), getFirst() +*/ + +/*! + \fn type *Q3PtrList::first() + + Returns a pointer to the first item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getFirst(), last(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::last() + + Returns a pointer to the last item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getLast(), first(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::next() + + Returns a pointer to the item succeeding the current item. Returns + 0 if the current item is 0 or equal to the last item. + + Makes the succeeding item current. If the current item before this + function call was the last item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::prev() + + Returns a pointer to the item preceding the current item. Returns + 0 if the current item is 0 or equal to the first item. + + Makes the preceding item current. If the current item before this + function call was the first item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), next(), current() +*/ + +/*! + \fn void Q3PtrList::toVector( Q3GVector *vec ) const + + Stores all list items in the vector \a vec. + + The vector must be of the same item type, otherwise the result + will be undefined. +*/ + +/*! + \typedef Q3PtrList::iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::Iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::ConstIterator + + \internal +*/ + +/*! + \typedef Q3PtrList::const_iterator + + \internal +*/ + +/*! + \fn Q3PtrList::constBegin() const + + \internal +*/ + +/*! + \fn Q3PtrList::constEnd() const + + \internal +*/ + +/*! + \fn Q3PtrList::erase(Iterator) + + \internal +*/ + + +/***************************************************************************** + Q3PtrListIterator documentation + *****************************************************************************/ + +/*! + \class Q3PtrListIterator + \brief The Q3PtrListIterator class provides an iterator for + Q3PtrList collections. + \compat + + Define a template instance Q3PtrListIterator\ to create a list + iterator that operates on Q3PtrList\ (list of X*). + + The following example is similar to the + example in the Q3PtrList class documentation, + but it uses Q3PtrListIterator. The class Employee is + defined there. + + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 + + Using a list iterator is a more robust way of traversing the list + than using the Q3PtrList member functions \link Q3PtrList::first() + first\endlink(), \link Q3PtrList::next() next\endlink(), \link + Q3PtrList::current() current\endlink(), etc., as many iterators can + traverse the same list independently. + + An iterator has its own current list item and can get the next and + previous list items. It doesn't modify the list in any way. + + When an item is removed from the list, all iterators that point to + that item are updated to point to Q3PtrList::current() instead to + avoid dangling references. + + \sa Q3PtrList +*/ + +/*! + \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList &list ) + + Constructs an iterator for \a list. The current iterator item is + set to point on the first item in the \a list. +*/ + +/*! + \fn Q3PtrListIterator::~Q3PtrListIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrListIterator::count() const + + Returns the number of items in the list this iterator operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrListIterator::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrListIterator::atFirst() const + + Returns TRUE if the current iterator item is the first list item; + otherwise returns FALSE. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3PtrListIterator::atLast() const + + Returns TRUE if the current iterator item is the last list item; + otherwise returns FALSE. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toFirst() + + Sets the current iterator item to point to the first list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toLast() + + Sets the current iterator item to point to the last list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toFirst(), atLast() +*/ + +/*! + \fn Q3PtrListIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::operator*() + + Asterisk operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::current() const + + Returns a pointer to the current iterator item. If the iterator is + positioned before the first item in the list or after the last + item in the list, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the list is empty, it + sets the current item to 0 and returns 0 +*/ + +/*! + \fn type *Q3PtrListIterator::operator--() + + Prefix - makes the preceding item current and returns the new + current item. + + If the current iterator item was the first item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn Q3PtrListIterator& Q3PtrListIterator::operator=( const Q3PtrListIterator &it ) + + Assignment. Makes a copy of the iterator \a it and returns a + reference to this iterator. +*/ + +/*! + \class Q3StrList + \brief The Q3StrList class provides a doubly-linked list of char*. + \compat + + If you want a string list of \l{QString}s use QStringList. + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrList can make deep or shallow copies of the strings that are + inserted. + + A deep copy means that memory is allocated for the string and then + the string data is copied into that memory. A shallow copy is just + a copy of the pointer value and not of the string data itself. + + The disadvantage of shallow copies is that because a pointer can + be deleted only once, the program must put all strings in a + central place and know when it is safe to delete them (i.e. when + the strings are no longer referenced by other parts of the + program). This can make the program more complex. The advantage of + shallow copies is that they consume far less memory than deep + copies. It is also much faster to copy a pointer (typically 4 or 8 + bytes) than to copy string data. + + A Q3StrList that operates on deep copies will, by default, turn on + auto-deletion (see setAutoDelete()). Thus, by default Q3StrList + will deallocate any string copies it allocates. + + The virtual compareItems() function is reimplemented and does a + case-sensitive string comparison. The inSort() function will + insert strings in sorted order. In general it is fastest to insert + the strings as they come and sort() at the end; inSort() is useful + when you just have to add a few extra strings to an already sorted + list. + + The Q3StrListIterator class is an iterator for Q3StrList. +*/ + +/*! + \fn Q3StrList::operator QList() const + + Automatically converts a Q3StrList into a QList. +*/ + +/*! + \fn Q3StrList::Q3StrList( bool deepCopies ) + + Constructs an empty list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrList::Q3StrList(const Q3StrList &list) + \fn Q3StrList::Q3StrList(const QList &list) + + Constructs a copy of \a list. +*/ + +/*! + \fn Q3StrList::~Q3StrList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) + \fn Q3StrList &Q3StrList::operator=(const QList &list) + + Assigns \a list to this list and returns a reference to this list. +*/ + +/*! + \class Q3StrIList + \brief The Q3StrIList class provides a doubly-linked list of char* + with case-insensitive comparison. + \compat + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrIList is identical to Q3StrList except that the virtual + compareItems() function is reimplemented to compare strings + case-insensitively. The inSort() function inserts strings in a + sorted order. In general it is fastest to insert the strings as + they come and sort() at the end; inSort() is useful when you just + have to add a few extra strings to an already sorted list. + + The Q3StrListIterator class works for Q3StrIList. + + \sa QStringList +*/ + +/*! + \fn Q3StrIList::Q3StrIList( bool deepCopies ) + + Constructs a list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrIList::~Q3StrIList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, + Q3PtrCollection::Item item2 ) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a item1 == \a item2 + \i nonzero if \a item1 != \a item2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return three values and use it to sort by: + + \list + \i 0 if \a item1 == \a item2 + \i \> 0 (positive integer) if \a item1 \> \a item2 + \i \< 0 (negative integer) if \a item1 \< \a item2 + \endlist + + inSort() requires that compareItems() is implemented as described + here. + + This function should not modify the list because some const + functions call compareItems(). + + The default implementation compares the pointers. +*/ + +/*! + \fn QDataStream& Q3PtrList::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a list item from the stream \a s and returns a reference to + the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrList::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a list item, \a item to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! \fn iterator Q3PtrList::begin() +\internal +*/ +/*! \fn const_iterator Q3PtrList::begin() const +\internal +*/ +/*! \fn iterator Q3PtrList::end() +\internal +*/ +/*! \fn const_iterator Q3PtrList::end() const +\internal +*/ + +/*! + \class Q3StrListIterator + \brief The Q3StrListIterator class is an iterator for the Q3StrList + and Q3StrIList classes. + \compat + + This class is a Q3PtrListIterator\ instance. It can traverse + the strings in the Q3StrList and Q3StrIList classes. +*/ + + +/* + \class Q3PtrListAutoDelete + \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. + \compat + + A Q3PtrListAutoDelete is identical to a Q3PtrList with + setAutoDelete(TRUE). +*/ diff --git a/doc/src/classes/q3ptrqueue.qdoc b/doc/src/classes/q3ptrqueue.qdoc new file mode 100644 index 0000000..b3af5f6 --- /dev/null +++ b/doc/src/classes/q3ptrqueue.qdoc @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrQueue + \brief The Q3PtrQueue class is a template class that provides a queue. + \compat + + Q3ValueVector can be used as an STL-compatible alternative to this + class. + + A template instance Q3PtrQueue\ is a queue that operates on + pointers to X (X*). + + A queue is a first in, first out structure. Items are added to the + tail of the queue with enqueue() and retrieved from the head with + dequeue(). You can peek at the head item without dequeing it using + head(). + + You can control the queue's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes, current() and + remove() are provided; both operate on the head(). + + \sa Q3PtrList Q3PtrStack +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue () + + Creates an empty queue with autoDelete() set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue& queue ) + + Creates a queue from \a queue. + + Only the pointers are copied; the items are not. The autoDelete() + flag is set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::~Q3PtrQueue() + + Destroys the queue. Items in the queue are deleted if autoDelete() + is TRUE. +*/ + +/*! + \fn Q3PtrQueue& Q3PtrQueue::operator= (const Q3PtrQueue& queue) + + Assigns \a queue to this queue and returns a reference to this + queue. + + This queue is first cleared and then each item in \a queue is + enqueued to this queue. Only the pointers are copied. + + \warning The autoDelete() flag is not modified. If it is TRUE for + both \a queue and this queue, deleting the two lists will cause \e + double-deletion of the items. +*/ + +/*! + \fn bool Q3PtrQueue::isEmpty() const + + Returns TRUE if the queue is empty; otherwise returns FALSE. + + \sa count() dequeue() head() +*/ + +/*! + \fn void Q3PtrQueue::enqueue (const type* d) + + Adds item \a d to the tail of the queue. + + \sa count() dequeue() +*/ + +/*! + \fn type* Q3PtrQueue::dequeue () + + Takes the head item from the queue and returns a pointer to it. + Returns 0 if the queue is empty. + + \sa enqueue() count() +*/ + +/*! + \fn bool Q3PtrQueue::remove() + + Removes the head item from the queue, and returns TRUE if there + was an item, i.e. the queue wasn't empty; otherwise returns FALSE. + + The item is deleted if autoDelete() is TRUE. + + \sa head() isEmpty() dequeue() +*/ + +/*! + \fn void Q3PtrQueue::clear() + + Removes all items from the queue, and deletes them if autoDelete() + is TRUE. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrQueue::count() const + + Returns the number of items in the queue. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::head() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn Q3PtrQueue::operator type*() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::current() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn bool Q3PtrQueue::autoDelete() const + + Returns the setting of the auto-delete option. The default is + FALSE. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrQueue::setAutoDelete( bool enable ) + + Sets the queue to auto-delete its contents if \a enable is TRUE + and not to delete them if \a enable is FALSE. + + If auto-deleting is turned on, all the items in a queue are + deleted when the queue itself is deleted. This can be quite + convenient if the queue has the only pointer to the items. + + The default setting is FALSE, for safety. If you turn it on, be + careful about copying the queue: you might find yourself with two + queues deleting the same items. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a queue item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a queue item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/classes/q3ptrstack.qdoc b/doc/src/classes/q3ptrstack.qdoc new file mode 100644 index 0000000..1650d69 --- /dev/null +++ b/doc/src/classes/q3ptrstack.qdoc @@ -0,0 +1,217 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrStack + \brief The Q3PtrStack class is a template class that provides a stack. + \compat + + Q3ValueStack is an STL-compatible alternative to this class. + + Define a template instance Q3PtrStack\ to create a stack that + operates on pointers to X, (X*). + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). Use top() to get a reference to the top element + without changing the stack. + + You can control the stack's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes current() and + remove() are provided; they both operate on the top(). + + \sa Q3PtrList Q3PtrQueue +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack () + + Creates an empty stack. +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack& s) + + Creates a stack by making a shallow copy of another stack \a s. +*/ + +/*! + \fn Q3PtrStack::~Q3PtrStack () + + Destroys the stack. All items will be deleted if autoDelete() is + true. +*/ + +/*! + \fn Q3PtrStack& Q3PtrStack::operator= (const Q3PtrStack& s) + + Sets the contents of this stack by making a shallow copy of + another stack \a s. Elements currently in this stack will be + deleted if autoDelete() is true. +*/ + +/*! + \fn bool Q3PtrStack::isEmpty () const + + Returns true if the stack contains no elements; otherwise returns + false. +*/ + +/*! + \fn void Q3PtrStack::push (const type* d) + + Adds an element \a d to the top of the stack. Last in, first out. +*/ + +/*! + \fn type* Q3PtrStack::pop () + + Removes the top item from the stack and returns it. The stack must + not be empty. +*/ + +/*! + \fn bool Q3PtrStack::remove () + + Removes the top item from the stack and deletes it if autoDelete() + is true. Returns true if there was an item to pop; otherwise + returns false. + + \sa clear() +*/ + +/*! + \fn void Q3PtrStack::clear() + + Removes all items from the stack, deleting them if autoDelete() is + true. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrStack::count() const + + Returns the number of items in the stack. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrStack::top () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn Q3PtrStack::operator type* ()const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn type* Q3PtrStack::current () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn bool Q3PtrStack::autoDelete() const + + The same as Q3PtrCollection::autoDelete(). Returns true if + the auto-delete option is set. If the option is set, the + stack auto-deletes its contents. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrStack::setAutoDelete(bool enable) + + Defines whether this stack auto-deletes its contents. The same as + Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete + is turned on. + + If auto-deleting is turned on, all the items in the stack are + deleted when the stack itself is deleted. This is convenient if + the stack has the only pointers to the items. + + The default setting is false, for safety. If you turn it on, be + careful about copying the stack, or you might find yourself with + two stacks deleting the same items. + + Note that the auto-delete setting may also affect other functions in + subclasses. For example, a subclass that has a remove() function + will remove the item from its data structure, and if auto-delete is + enabled, will also delete the item. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) + + Reads a stack item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrStack::write(QDataStream& s, + Q3PtrCollection::Item item) const + + Writes a stack item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/classes/q3ptrvector.qdoc b/doc/src/classes/q3ptrvector.qdoc new file mode 100644 index 0000000..fa78de5 --- /dev/null +++ b/doc/src/classes/q3ptrvector.qdoc @@ -0,0 +1,427 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrVector + \brief The Q3PtrVector class is a template collection class that + provides a vector (array). + \compat + + Q3ValueVector is an STL-compatible alternative to this class. + + Q3PtrVector is implemented as a template class. Defines a template + instance Q3PtrVector\ to create a vector that contains pointers + to X (X*). + + A vector is the same as an array. The main difference between + Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the + elements, whereas Q3MemArray stores the elements themselves (i.e. + Q3MemArray is value-based and Q3PtrVector is pointer-based). + + Items are added to the vector using insert() or fill(). Items are + removed with remove(). You can get a pointer to an item at a + particular index position using at(). + + Unless otherwise stated, all functions that remove items from the + vector will also delete the element pointed to if \link + setAutoDelete() auto-deletion\endlink is enabled. By default, + auto-deletion is disabled; see setAutoDelete(). This behavior can + be changed in a subclass by reimplementing the virtual function + deleteItem(). + + Functions that compare items (find() and sort() for example) will + do so using the virtual function compareItems(). The default + implementation of this function only compares the pointer values. + Reimplement compareItems() in a subclass to get searching and + sorting based on the item contents. You can perform a linear + search for a pointer in the vector using findRef(), or a binary + search (of a sorted vector) using bsearch(). You can count the + number of times an item appears in the vector with contains() or + containsRef(). + + \sa Q3MemArray +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(uint size) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector &v) + + Constructs a copy of \a v. Only the pointers are copied (i.e. + shallow copy). +*/ + +/*! + \fn Q3PtrVector::~Q3PtrVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn Q3PtrVector &Q3PtrVector::operator=(const Q3PtrVector &v) + + Assigns \a v to this vector and returns a reference to this + vector. + + This vector is first cleared and then all the items from \a v are + copied into the vector. Only the pointers are copied (i.e. shallow + copy). + + \sa clear() +*/ + +/*! + \fn type **Q3PtrVector::data() const + + Returns a pointer to the actual vector data, which is an array of + type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3PtrVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint Q3PtrVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::isEmpty() const + + Returns true if the vector is empty; otherwise returns false. + + \sa count() +*/ + +/*! + \fn bool Q3PtrVector::isNull() const + + Returns true if the vector is null; otherwise returns false. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool Q3PtrVector::resize(uint size) + + Resizes (expands or shrinks) the vector to \a size elements. The + vector becomes a null vector if \a size == 0. + + Any items at position \a size or beyond in the vector are removed. + New positions are initialized to 0. + + Returns true if successful, i.e. if the memory was successfully + allocated; otherwise returns false. + + \sa size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::insert(uint i, const type *d) + + Sets position \a i in the vector to contain the item \a d. \a i + must be less than size(). Any previous element in position \a i is + removed. + + Returns true if \a i is within range; otherwise returns false. + + \sa at() +*/ + +/*! + \fn bool Q3PtrVector::remove(uint i) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns true if \a i is within range; otherwise returns false. + + \sa take(), at() +*/ + +/*! + \fn type* Q3PtrVector::take(uint i) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is + no item at position \a i, 0 is returned. + + Unlike remove(), this function does \e not call deleteItem() for + the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void Q3PtrVector::clear() + + Removes all items from the vector, and destroys the vector itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool Q3PtrVector::fill(const type *d, int size) + + Inserts item \a d in all positions in the vector. Any existing + items are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By + default, \a size is -1. + + Returns true if successful, i.e. \a size is the same as the + current size, or \a size is larger and the memory has successfully + been allocated; otherwise returns false. + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void Q3PtrVector::sort() + + Sorts the items in ascending order. Any empty positions will be + put last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int Q3PtrVector::bsearch(const type* d) const + + In a sorted array, finds the first occurrence of \a d using a + binary search. For a sorted array, this is generally much faster + than find(), which performs a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a + d must not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int Q3PtrVector::findRef(const type *d, uint i) const + + Finds the first occurrence of the item pointer \a d in the vector + using a linear search. The search starts at position \a i, which + must be less than size(). \a i is by default 0; i.e. the search + starts at the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + Use the much faster bsearch() to search a sorted vector. + + \sa find(), bsearch() +*/ + +/*! + \fn int Q3PtrVector::find(const type *d, uint i) const + + Finds the first occurrence of item \a d in the vector using a + linear search. The search starts at position \a i, which must be + less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + Compares items using the virtual function compareItems(). + + Use the much faster bsearch() to search a sorted vector. + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint Q3PtrVector::containsRef(const type *d) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint Q3PtrVector::contains(const type *d) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *Q3PtrVector::operator[](int i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at(\a i). + + \sa at() +*/ + +/*! + \fn type *Q3PtrVector::at(uint i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void Q3PtrVector::toList(Q3GList *list) const + + \internal + + Copies all items in this vector to the list \a list. \a list is + first cleared and then all items are appended to \a list. + + \sa Q3PtrList, Q3PtrStack, Q3PtrQueue +*/ + +/*! + \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, + Q3PtrCollection::Item d2) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a d1 == \a d2 + \i nonzero if \a d1 != \a d2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return one of three values and use it to + sort by: + \list + \i 0 if \a d1 == \a d2 + \i \> 0 (positive integer) if \a d1 \> \a d2 + \i \< 0 (negative integer) if \a d1 \< \a d2 + \endlist + + The sort() and bsearch() functions require compareItems() to be + implemented as described here. + + This function should not modify the vector because some const + functions call compareItems(). +*/ + +/*! + \fn QDataStream& Q3PtrVector::read(QDataStream &s, + Q3PtrCollection::Item &item) + + Reads a vector item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrVector::write(QDataStream &s, + Q3PtrCollection::Item item) const + + Writes a vector item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! + \fn bool Q3PtrVector::operator==(const Q3PtrVector &v) const + + Returns true if this vector and \a v are equal; otherwise returns + false. +*/ diff --git a/doc/src/classes/q3sqlfieldinfo.qdoc b/doc/src/classes/q3sqlfieldinfo.qdoc new file mode 100644 index 0000000..ba064f3 --- /dev/null +++ b/doc/src/classes/q3sqlfieldinfo.qdoc @@ -0,0 +1,234 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlFieldInfo + \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. + + \compat + + Q3SqlFieldInfo objects only store meta data; field values are + stored in QSqlField objects. + + All values must be set in the constructor, and may be retrieved + using isRequired(), type(), length(), precision(), defaultValue(), + name(), isGenerated() and typeID(). + + \sa Q3SqlRecordInfo +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, + QVariant::Type typ, + int required, + int len, + int prec, + const QVariant& defValue, + int typeID, + bool generated, + bool trim, + bool calculated) + + Constructs a Q3SqlFieldInfo with the following parameters: + \table + \row \i \a name \i the name of the field. + \row \i \a typ \i the field's type in a QVariant. + \row \i \a required \i greater than 0 if the field is required, 0 + if its value can be NULL and less than 0 if it cannot be + determined whether the field is required or not. + \row \i \a len \i the length of the field. Note that for + non-character types some databases return either the length in + bytes or the number of digits. -1 signifies that the length cannot + be determined. + \row \i \a prec \i the precision of the field, or -1 if the field + has no precision or it cannot be determined. + \row \i \a defValue \i the default value that is inserted into + the table if none is specified by the user. QVariant() if there is + no default value or it cannot be determined. + \row \i \a typeID \i the internal typeID of the database system + (only useful for low-level programming). 0 if unknown. + \row \i \a generated \i TRUE indicates that this field should be + included in auto-generated SQL statments, e.g. in Q3SqlCursor. + \row \i \a trim \i TRUE indicates that widgets should remove + trailing whitespace from character fields. This does not affect + the field value but only its representation inside widgets. + \row \i \a calculated \i TRUE indicates that the value of this + field is calculated. The value of calculated fields can by + modified by subclassing Q3SqlCursor and overriding + Q3SqlCursor::calculateField(). + \endtable +*/ + +/*! + \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() + + Destroys the object and frees any allocated resources. +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) + + Creates a Q3SqlFieldInfo object with the type and the name of the + QSqlField \a other. +*/ + +/*! + \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const + + Assigns \a other to this field info and returns a reference to it. +*/ + +/*! + \fn QSqlField Q3SqlFieldInfo::toField() const + + Returns an empty QSqlField based on the information in this + Q3SqlFieldInfo. +*/ + +/*! + \fn int Q3SqlFieldInfo::isRequired() const + + Returns a value greater than 0 if the field is required (NULL + values are not allowed), 0 if it isn't required (NULL values are + allowed) or less than 0 if it cannot be determined whether the + field is required or not. +*/ + +/*! + \fn QVariant::Type Q3SqlFieldInfo::type() const + + Returns the field's type or QVariant::Invalid if the type is + unknown. +*/ + +/*! + \fn int Q3SqlFieldInfo::length() const + + Returns the field's length. For fields storing text the return + value is the maximum number of characters the field can hold. For + non-character fields some database systems return the number of + bytes needed or the number of digits allowed. If the length cannot + be determined -1 is returned. +*/ + +/*! + \fn int Q3SqlFieldInfo::precision() const + + Returns the field's precision or -1 if the field has no precision + or it cannot be determined. +*/ + +/*! + \fn QVariant Q3SqlFieldInfo::defaultValue() const + + Returns the field's default value or an empty QVariant if the + field has no default value or the value couldn't be determined. + The default value is the value inserted in the database when it + is not explicitly specified by the user. +*/ + +/*! + \fn QString Q3SqlFieldInfo::name() const + + Returns the name of the field in the SQL table. +*/ + +/*! + \fn int Q3SqlFieldInfo::typeID() const + + Returns the internal type identifier as returned from the database + system. The return value is 0 if the type is unknown. +*/ + +/*! + \fn bool Q3SqlFieldInfo::isGenerated() const + + Returns TRUE if the field should be included in auto-generated + SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. + + \sa setGenerated() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isTrim() const + + Returns TRUE if trailing whitespace should be removed from + character fields; otherwise returns FALSE. + + \sa setTrim() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isCalculated() const + + Returns TRUE if the field is calculated; otherwise returns FALSE. + + \sa setCalculated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setTrim(bool trim) + + If \a trim is TRUE widgets should remove trailing whitespace from + character fields. This does not affect the field value but only + its representation inside widgets. + + \sa isTrim() +*/ + +/*! + \fn void Q3SqlFieldInfo::setGenerated(bool generated) + + \a generated set to FALSE indicates that this field should not appear + in auto-generated SQL statements (for example in Q3SqlCursor). + + \sa isGenerated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setCalculated(bool calculated) + + \a calculated set to TRUE indicates that this field is a calculated + field. The value of calculated fields can by modified by subclassing + Q3SqlCursor and overriding Q3SqlCursor::calculateField(). + + \sa isCalculated() +*/ diff --git a/doc/src/classes/q3sqlrecordinfo.qdoc b/doc/src/classes/q3sqlrecordinfo.qdoc new file mode 100644 index 0000000..64236d2 --- /dev/null +++ b/doc/src/classes/q3sqlrecordinfo.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlRecordInfo + \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. + + \compat + + This class is a list that holds a set of database field meta + data. Use contains() to see if a given field name exists in the + record, and use find() to get a QSqlFieldInfo record for a named + field. + + \sa Q3SqlFieldInfo +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo() + + Constructs an empty record info object. +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) + + Constructs a copy of \a other. +*/ + +/*! + \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const + + Returns the number of times a field called \a fieldName occurs in + the record. Returns 0 if no field by that name could be found. +*/ + +/*! + \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const + + Returns a QSqlFieldInfo object for the first field in the record + which has the field name \a fieldName. If no matching field is + found then an empty QSqlFieldInfo object is returned. +*/ + +/*! + \fn QSqlRecord Q3SqlRecordInfo::toRecord() const + + Returns an empty QSqlRecord based on the field information + in this Q3SqlRecordInfo. +*/ diff --git a/doc/src/classes/q3valuelist.qdoc b/doc/src/classes/q3valuelist.qdoc new file mode 100644 index 0000000..fd73763 --- /dev/null +++ b/doc/src/classes/q3valuelist.qdoc @@ -0,0 +1,569 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueList + \brief The Q3ValueList class is a value-based template class that + provides lists. + \compat + + Q3ValueList is a Qt implementation of an STL-like list container. + It can be used in your application if the standard \c list is not + available for your target platforms. + + Q3ValueList\ defines a template instance to create a list of + values that all have the class T. Note that Q3ValueList does not + store pointers to the members of the list; it holds a copy of + every member. This is why these kinds of classes are called "value + based"; Q3PtrList and Q3Dict are "pointer based". + + Q3ValueList contains and manages a collection of objects of type T + and provides iterators that allow the contained objects to be + addressed. Q3ValueList owns the contained items. For more relaxed + ownership semantics, see Q3PtrCollection and friends which are + pointer-based containers. + + Some classes cannot be used within a Q3ValueList, for example, all + classes derived from QObject and thus all classes that implement + widgets. Only values can be used in a Q3ValueList. To qualify as a + value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + In addition, some compilers (e.g. Sun CC) might require that the + class provides an equality operator (operator==()). + + Q3ValueList's function naming is consistent with the other Qt + classes (e.g. count(), isEmpty()). Q3ValueList also provides extra + functions for compatibility with STL algorithms, such as size() + and empty(). Programmers already familiar with the STL \c list may + prefer to use the STL-compatible functions. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 + + + Notice that the latest changes to Mary's salary did not affect the + value in the list because the list created a copy of Mary's entry. + + There are several ways to find items in the list. The begin() and + end() functions return iterators to the beginning and end of the + list. The advantage of getting an iterator is that you can move + forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the item which is one \e past the last item in the + container. The past-the-end iterator is still associated with the + list it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the list is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + It is safe to have multiple iterators a the list at the same + time. If some member of the list is removed, only iterators + pointing to the removed member become invalid. Inserting into the + list does not invalidate any iterator. For convenience, the + function last() returns a reference to the last item in the list, + and first() returns a reference to the first item. If the + list is empty(), both last() and first() have undefined behavior + (your application will crash or do unpredictable things). Use + last() and first() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 + + Because Q3ValueList is value-based there is no need to be careful + about deleting items in the list. The list holds its own copies + and will free them if the corresponding member or the list itself + is deleted. You can force the list to free all of its items with + clear(). + + Q3ValueList is shared implicitly, which means it can be copied in + constant time, i.e. O(1). If multiple Q3ValueList instances share + the same data and one needs to modify its contents, this modifying + instance makes a copy and modifies its private copy; therefore it + does not affect the other instances; this takes O(n) time. This is + often called "copy on write". If a Q3ValueList is being used in a + multi-threaded program, you must protect all access to the list. + See \l QMutex. + + There are several ways to insert items into the list. The + prepend() and append() functions insert items at the beginning and + the end of the list respectively. The insert() function comes in + several flavors and can be used to add one or more items at + specific positions within the list. + + Items can also be removed from the list in several ways. There + are several variants of the remove() function, which removes a + specific item from the list. The remove() function will find and + remove items according to a specific item value. + + \sa Q3ValueListIterator +*/ + +/*! \typedef Q3ValueList::iterator + The list's iterator type, Q3ValueListIterator. */ +/*! \typedef Q3ValueList::const_iterator + The list's const iterator type, Q3ValueListConstIterator. */ +/*! \typedef Q3ValueList::value_type + The type of the object stored in the list, T. */ +/*! \typedef Q3ValueList::pointer + The pointer to T type. */ +/*! \typedef Q3ValueList::const_pointer + The const pointer to T type. */ +/*! \typedef Q3ValueList::reference + The reference to T type. */ +/*! \typedef Q3ValueList::const_reference + The const reference to T type. */ +/*! \typedef Q3ValueList::size_type + An unsigned integral type, used to represent various sizes. */ +/*! \typedef Q3ValueList::difference_type + \internal +*/ +/*! + \fn Q3ValueList::Q3ValueList() + + Constructs an empty list. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const Q3ValueList& l ) + \fn Q3ValueList::Q3ValueList( const QList& l ) + \fn Q3ValueList::Q3ValueList( const QLinkedList& l ) + + Constructs a copy of \a l. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const std::list& l ) + + Contructs a copy of \a l. + + This constructor is provided for compatibility with STL + containers. +*/ + +/*! + \fn Q3ValueList::~Q3ValueList() + + Destroys the list. References to the values in the list and all + iterators of this list become invalidated. Note that it is + impossible for an iterator to check whether or not it is valid: + Q3ValueList is highly tuned for performance, not for error + checking. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const std::list& l ) const + + \overload + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. + + This operator is provided for compatibility with STL containers. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const Q3ValueList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. The cost of such an assignment is O(1) since Q3ValueList + is implicitly shared. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const QList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const std::list& l ) + + \overload + + Assigns the contents of \a l to the list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn bool Q3ValueList::operator!= ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are unequal; otherwise returns + FALSE. +*/ + +/*! + \fn iterator Q3ValueList::insert( typename Q3ValueList::Iterator it, const T& x ) + + Inserts the value \a x in front of the item pointed to by the + iterator, \a it. + + Returns an iterator pointing at the inserted item. + + \sa append(), prepend() +*/ + +/*! + \fn uint Q3ValueList::remove( const T& x ) + + \overload + + Removes all items that have value \a x and returns the number of + removed items. +*/ + +/*! + \fn QDataStream& operator>>( QDataStream& s, Q3ValueList& l ) + + \relates Q3ValueList + + Reads a list, \a l, from the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList& l ) + + \overload + \relates Q3ValueList + + Writes a list, \a l, to the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn void Q3ValueList::insert( typename Q3ValueList::Iterator pos, + typename Q3ValueList::size_type n, const T& x ) + + \overload + + Inserts \a n copies of \a x before position \a pos. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator<< ( const T& x ) + + Adds the value \a x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn const T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) const + + Returns a const reference to the item with index \a i in the list. + It is up to you to check whether this item really exists. You can + do that easily with the count() function. However this operator + does not check whether \a i is in range and will deliver undefined + results if it does not exist. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) + + \overload + + Returns a non-const reference to the item with index \a i. +*/ + +/*! + \fn const_iterator Q3ValueList::at( typename Q3ValueList::size_type i ) const + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn iterator Q3ValueList::at( typename Q3ValueList::size_type i ) + + \overload + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + +*/ + +/*! + \fn iterator Q3ValueList::fromLast() + + \overload + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 + +*/ + +/*! + \fn const_iterator Q3ValueList::fromLast() const + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 + +*/ + +/*! + \fn Q3ValueList Q3ValueList::operator+( const Q3ValueList& l ) const + + Creates a new list and fills it with the items of this list. Then + the items of \a l are appended. Returns the new list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const Q3ValueList& l ) + + Appends the items of \a l to this list. Returns a reference to + this list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const T& x ) + + \overload + + Appends the value \a x to the list. Returns a reference to the + list. +*/ + +/*! + \fn iterator Q3ValueList::append( const T& x ) + + Inserts \a x at the end of the list. + + \sa insert(), prepend() +*/ + +/*! + \fn iterator Q3ValueList::prepend( const T& x ) + + Inserts \a x at the beginning of the list. + + \sa insert(), append() +*/ + +/*! + \fn iterator Q3ValueList::remove( typename Q3ValueList::Iterator it ) + + Removes the item pointed to by \a it from the list. No iterators + other than \a it or other iterators pointing at the same item as + \a it are invalidated. Returns an iterator to the next item after + \a it, or end() if there is no such item. + + \sa clear() +*/ + +/*! + \fn uint Q3ValueList::contains( const T& x ) const + + Returns the number of occurrences of the value \a x in the list. +*/ + +/*! + \class Q3ValueListIterator + \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. + \compat + + An iterator is a class for accessing the items of a container + class: a generalization of the index in an array. A pointer + into a "const char *" and an index into an "int[]" are both + iterators, and the general idea is to provide that functionality + for any data structure. + + The Q3ValueListIterator class is an iterator for Q3ValueList + instantiations. You can create the appropriate iterator type by + using the \c iterator typedef provided by Q3ValueList. + + The only way to access the items in a Q3ValueList is to use an + iterator. + + Example (see Q3ValueList for the complete code): + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 + + Q3ValueList is highly optimized for performance and memory usage. + This means that you must be careful: Q3ValueList does not know + about all its iterators and the iterators don't know to which list + they belong. This makes things very fast, but if you're not + careful, you can get spectacular bugs. Always make sure iterators + are valid before dereferencing them or using them as parameters to + generic algorithms in the STL. + + Using an invalid iterator is undefined (your application will + probably crash). Many Qt functions return const value lists; to + iterate over these you should make a copy and iterate over the + copy. + + For every Iterator there is a ConstIterator. When accessing a + Q3ValueList in a const environment or if the reference or pointer + to the list is itself const, then you must use the ConstIterator. + Its semantics are the same as the Iterator, but it only returns + const references. + + \sa Q3ValueList, Q3ValueListConstIterator +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) + \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList::iterator &o) + + Constucts a copy of iterator \a o. +*/ + +/*! + \class Q3ValueListConstIterator + \brief The Q3ValueListConstIterator class provides a const iterator + for Q3ValueList. + \compat + + In contrast to Q3ValueListIterator, this class is used to iterate + over a const list. It does not allow modification of the values of + the list since that would break const semantics. + + You can create the appropriate const iterator type by using the \c + const_iterator typedef provided by Q3ValueList. + + For more information on Q3ValueList iterators, see + Q3ValueListIterator. + + \sa Q3ValueListIterator, Q3ValueList +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::const_iterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::iterator &o) + + Constructs a copy of iterator \a o. +*/ + +/*! + \typedef Q3ValueList::Iterator + + This iterator is an instantiation of Q3ValueListIterator for the + same type as this Q3ValueList. In other words, if you instantiate + Q3ValueList, Iterator is a Q3ValueListIterator. Several + member function use it, such as Q3ValueList::begin(), which returns + an iterator pointing to the first item in the list. + + Functionally, this is almost the same as ConstIterator. The only + difference is that you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator ConstIterator +*/ + +/*! + \typedef Q3ValueList::ConstIterator + + This iterator is an instantiation of Q3ValueListConstIterator for + the same type as this Q3ValueList. In other words, if you + instantiate Q3ValueList, ConstIterator is a + Q3ValueListConstIterator. Several member function use it, such + as Q3ValueList::begin(), which returns an iterator pointing to the + first item in the list. + + Functionally, this is almost the same as Iterator. The only + difference is you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator Iterator +*/ + +/*! + \fn Q3ValueList::operator QList() const + + Automatically converts a Q3ValueList into a QList. +*/ diff --git a/doc/src/classes/q3valuestack.qdoc b/doc/src/classes/q3valuestack.qdoc new file mode 100644 index 0000000..e3ae677 --- /dev/null +++ b/doc/src/classes/q3valuestack.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueStack + \brief The Q3ValueStack class is a value-based template class that provides a stack. + \compat + + Define a template instance Q3ValueStack\ to create a stack of + values that all have the class X. + + Note that Q3ValueStack does not store pointers to the members of + the stack; it holds a copy of every member. That is why these + kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, + Q3Dict, etc., are "pointer based". + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). The top() function provides access to the topmost item + without removing it. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 + + Q3ValueStack is a specialized Q3ValueList provided for convenience. + All of Q3ValueList's functionality also applies to Q3PtrStack, for + example the facility to iterate over all elements using + Q3ValueStack::Iterator. See Q3ValueListIterator for further + details. + + Some classes cannot be used within a Q3ValueStack, for example + everything derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueStack. To + qualify as a value, the class must provide + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. +*/ + + +/*! + \fn Q3ValueStack::Q3ValueStack() + + Constructs an empty stack. +*/ + +/*! + \fn Q3ValueStack::~Q3ValueStack() + + Destroys the stack. References to the values in the stack and all + iterators of this stack become invalidated. Because Q3ValueStack is + highly tuned for performance, you won't see warnings if you use + invalid iterators because it is impossible for an iterator to + check whether or not it is valid. +*/ + + +/*! + \fn void Q3ValueStack::push( const T& d ) + + Adds element, \a d, to the top of the stack. Last in, first out. + + This function is equivalent to append(). + + \sa pop(), top() +*/ + +/*! + \fn T& Q3ValueStack::top() + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. Note that you must not + change the value the end() iterator points to. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + + +/*! + \fn const T& Q3ValueStack::top() const + + \overload + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + +/*! + \fn T Q3ValueStack::pop() + + Removes the top item from the stack and returns it. + + \sa top() push() +*/ + + + + + diff --git a/doc/src/classes/q3valuevector.qdoc b/doc/src/classes/q3valuevector.qdoc new file mode 100644 index 0000000..353b7fa --- /dev/null +++ b/doc/src/classes/q3valuevector.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueVector + \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. + \compat + + Q3ValueVector is a Qt implementation of an STL-like vector + container. It can be used in your application if the standard \c + vector is not available for your target platforms. + + Q3ValueVector\ defines a template instance to create a vector + of values that all have the class T. Q3ValueVector does not store + pointers to the members of the vector; it holds a copy of every + member. Q3ValueVector is said to be value based; in contrast, + Q3PtrList and Q3Dict are pointer based. + + Q3ValueVector contains and manages a collection of objects of type + T and provides random access iterators that allow the contained + objects to be addressed. Q3ValueVector owns the contained + elements. For more relaxed ownership semantics, see Q3PtrCollection + and friends, which are pointer-based containers. + + Q3ValueVector provides good performance if you append or remove + elements from the end of the vector. If you insert or remove + elements from anywhere but the end, performance is very bad. The + reason for this is that elements must to be copied into new + positions. + + Some classes cannot be used within a Q3ValueVector: for example, + all classes derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueVector. To + qualify as a value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e., a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + Q3ValueVector uses an STL-like syntax to manipulate and address the + objects it contains. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 + + As you can see, the most recent change to Joe's salary did not + affect the value in the vector because the vector created a copy + of Joe's entry. + + Many Qt functions return const value vectors; to iterate over + these you should make a copy and iterate over the copy. + + There are several ways to find items in the vector. The begin() + and end() functions return iterators to the beginning and end of + the vector. The advantage of getting an iterator is that you can + move forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the element which is one past the last element in + the container. The past-the-end iterator is still associated with + the vector it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the vector is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + The fastest way to access an element of a vector is by using + operator[]. This function provides random access and will return + a reference to the element located at the specified index. Thus, + you can access every element directly, in constant time, providing + you know the location of the element. It is undefined to access + an element that does not exist (your application will probably + crash). For example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 + + Whenever inserting, removing or referencing elements in a vector, + always make sure you are referring to valid positions. For + example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 + + The iterators provided by vector are random access iterators, + therefore you can use them with many generic algorithms, for + example, algorithms provided by the STL. + + It is safe to have multiple iterators on the vector at the same + time. Since Q3ValueVector manages memory dynamically, all iterators + can become invalid if a memory reallocation occurs. For example, + if some member of the vector is removed, iterators that point to + the removed element and to all following elements become + invalidated. Inserting into the middle of the vector will + invalidate all iterators. For convenience, the function back() + returns a reference to the last element in the vector, and front() + returns a reference to the first element. If the vector is + empty(), both back() and front() have undefined behavior (your + application will crash or do unpredictable things). Use back() and + front() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 + + Because Q3ValueVector manages memory dynamically, it is recommended + that you contruct a vector with an initial size. Inserting and + removing elements happens fastest when: + \list + \i Inserting or removing elements happens at the end() of the + vector; + \i The vector does not need to allocate additional memory. + \endlist + + By creating a Q3ValueVector with a sufficiently large initial size, + there will be less memory allocations. Do not use an initial size + that is too big, since it will still take time to construct all + the empty entries, and the extra space will be wasted if it is + never used. + + Because Q3ValueVector is value-based there is no need to be careful + about deleting elements in the vector. The vector holds its own + copies and will free them if the corresponding member or the + vector itself is deleted. You can force the vector to free all of + its items with clear(). + + Q3ValueVector is shared implicitly, which means it can be copied in + constant time. If multiple Q3ValueVector instances share the same + data and one needs to modify its contents, this modifying instance + makes a copy and modifies its private copy; it thus does not + affect the other instances. This is often called "copy on write". + If a Q3ValueVector is being used in a multi-threaded program, you + must protect all access to the vector. See QMutex. + + There are several ways to insert elements into the vector. The + push_back() function insert elements into the end of the vector, + and is usually fastest. The insert() function can be used to add + elements at specific positions within the vector. + + Items can be also be removed from the vector in several ways. + There are several variants of the erase() function which removes a + specific element, or range of elements, from the vector. + + Q3ValueVector stores its elements in contiguous memory. This means + that you can use a Q3ValueVector in any situation that requires an + array. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector() + + Constructs an empty vector without any elements. To create a + vector which reserves an initial amount of space for elements, use + \c Q3ValueVector(size_type n). +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector& v ) + + Constructs a copy of \a v. + + This operation costs O(1) time because Q3ValueVector is implicitly + shared. + + The first modification to the vector does takes O(n) time, because + the elements must be copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const std::vector& v ) + + This operation costs O(n) time because \a v is copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( QVector::size_type n, const T& val ) + + Constructs a vector with an initial size of \a n elements. Each + element is initialized with the value of \a val. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const Q3ValueVector& v ) + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of such an assignment is O(1) since + Q3ValueVector is implicitly shared. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const std::vector& v ) + + \overload + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of this assignment is O(n) since \a v is + copied. +*/ + +/*! + \fn T &Q3ValueVector::at( int i , bool* ok ) + + Returns a reference to the element with index \a i. If \a ok is + non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn const T &Q3ValueVector::at( int i , bool* ok ) const + + \overload + + Returns a const reference to the element with index \a i. If \a ok + is non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn void Q3ValueVector::resize( int n, const T& val = T() ) + + Changes the size of the vector to \a n. If \a n is greater than + the current size(), elements are added to the end and initialized + with the value of \a val. If \a n is less than size(), elements + are removed from the end. If \a n is equal to size() nothing + happens. +*/ diff --git a/doc/src/classes/qalgorithms.qdoc b/doc/src/classes/qalgorithms.qdoc new file mode 100644 index 0000000..7634322 --- /dev/null +++ b/doc/src/classes/qalgorithms.qdoc @@ -0,0 +1,651 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Generic Algorithms + \ingroup architecture + + \brief The header provides generic template-based algorithms. + + Qt provides a number of global template functions in \c + that work on containers and perform well-know + algorithms. You can use these algorithms with any \l {container + class} that provides STL-style iterators, including Qt's QList, + QLinkedList, QVector, QMap, and QHash classes. + + These functions have taken their inspiration from similar + functions available in the STL \c header. Most of them + have a direct STL equivalent; for example, qCopyBackward() is the + same as STL's copy_backward() algorithm. + + If STL is available on all your target platforms, you can use the + STL algorithms instead of their Qt counterparts. One reason why + you might want to use the STL algorithms is that STL provides + dozens and dozens of algorithms, whereas Qt only provides the most + important ones, making no attempt to duplicate functionality that + is already provided by the C++ standard. + + Most algorithms take \l {STL-style iterators} as parameters. The + algorithms are generic in the sense that they aren't bound to a + specific iterator class; you can use them with any iterators that + meet a certain set of requirements. + + Let's take the qFill() algorithm as an example. Unlike QVector, + QList has no fill() function that can be used to fill a list with + a particular value. If you need that functionality, you can use + qFill(): + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 + + qFill() takes a begin iterator, an end iterator, and a value. + In the example above, we pass \c list.begin() and \c list.end() + as the begin and end iterators, but this doesn't have to be + the case: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 + + Different algorithms can have different requirements for the + iterators they accept. For example, qFill() accepts two + \l {forward iterators}. The iterator types required are specified + for each algorithm. If an iterator of the wrong type is passed (for + example, if QList::ConstIterator is passed as an \l {output + iterator}), you will always get a compiler error, although not + necessarily a very informative one. + + Some algorithms have special requirements on the value type + stored in the containers. For example, qEqual() requires that the + value type supports operator==(), which it uses to compare items. + Similarly, qDeleteAll() requires that the value type is a + non-const pointer type (for example, QWidget *). The value type + requirements are specified for each algorithm, and the compiler + will produce an error if a requirement isn't met. + + \target binaryFind example + + The generic algorithms can be used on other container classes + than those provided by Qt and STL. The syntax of STL-style + iterators is modeled after C++ pointers, so it's possible to use + plain arrays as containers and plain pointers as iterators. A + common idiom is to use qBinaryFind() together with two static + arrays: one that contains a list of keys, and another that + contains a list of associated values. For example, the following + code will look up an HTML entity (e.g., \c &) in the \c + name_table array and return the corresponding Unicode value from + the \c value_table if the entity is recognized: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 + + This kind of code is for advanced users only; for most + applications, a QMap- or QHash-based approach would work just as + well: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 + + \section1 Types of Iterators + + The algorithms have certain requirements on the iterator types + they accept, and these are specified individually for each + function. The compiler will produce an error if a requirement + isn't met. + + \section2 Input Iterators + + An \e{input iterator} is an iterator that can be used for reading + data sequentially from a container. It must provide the following + operators: \c{==} and \c{!=} for comparing two iterators, unary + \c{*} for retrieving the value stored in the item, and prefix + \c{++} for advancing to the next item. + + The Qt containers' iterator types (const and non-const) are all + input iterators. + + \section2 Output Iterators + + An \e{output iterator} is an iterator that can be used for + writing data sequentially to a container or to some output + stream. It must provide the following operators: unary \c{*} for + writing a value (i.e., \c{*it = val}) and prefix \c{++} for + advancing to the next item. + + The Qt containers' non-const iterator types are all output + iterators. + + \section2 Forward Iterators + + A \e{forward iterator} is an iterator that meets the requirements + of both input iterators and output iterators. + + The Qt containers' non-const iterator types are all forward + iterators. + + \section2 Bidirectional Iterators + + A \e{bidirectional iterator} is an iterator that meets the + requirements of forward iterators but that in addition supports + prefix \c{--} for iterating backward. + + The Qt containers' non-const iterator types are all bidirectional + iterators. + + \section2 Random Access Iterators + + The last category, \e{random access iterators}, is the most + powerful type of iterator. It supports all the requirements of a + bidirectional iterator, and supports the following operations: + + \table + \row \i \c{i += n} \i advances iterator \c i by \c n positions + \row \i \c{i -= n} \i moves iterator \c i back by \c n positions + \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c + n positions ahead of iterator \c i + \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i + \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j + \row \i \c{i[n]} \i same as \c{*(i + n)} + \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i + \endtable + + QList and QVector's non-const iterator types are random access iterators. + + \sa {container classes}, +*/ + +/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [\a + begin2, ...), in the order in which they appear. + + The item at position \a begin1 is assigned to that at position \a + begin2; the item at position \a begin1 + 1 is assigned to that at + position \a begin2 + 1; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 + + \sa qCopyBackward(), {input iterators}, {output iterators} +*/ + +/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [..., + \a end2). + + The item at position \a end1 - 1 is assigned to that at position + \a end2 - 1; the item at position \a end1 - 2 is assigned to that + at position \a end2 - 2; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 + + \sa qCopy(), {bidirectional iterators} +*/ + +/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) + \relates + + Compares the items in the range [\a begin1, \a end1) with the + items in the range [\a begin2, ...). Returns true if all the + items compare equal; otherwise returns false. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) + \relates + + Fills the range [\a begin, \a end) with \a value. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 + + \sa qCopy(), {forward iterators} +*/ + +/*! \fn void qFill(Container &container, const T &value) + \relates + + \overload + + This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); +*/ + +/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) + \relates + + Returns an iterator to the first occurrence of \a value in a + container in the range [\a begin, \a end). Returns \a end if \a + value isn't found. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + If the items in the range are in ascending order, you can get + faster results by using qLowerBound() or qBinaryFind() instead of + qFind(). + + \sa qBinaryFind(), {input iterators} +*/ + +/*! \fn void qFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); +*/ + +/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) + \relates + + Returns the number of occurrences of \a value in the range [\a begin, \a end), + which is returned in \a n. \a n is never initialized, the count is added to \a n. + It is the caller's responsibility to initialize \a n. + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 + + This function requires the item type (in the example above, + \c int) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qCount(const Container &container, const T &value, Size &n) +\relates + +\overload + +Instead of operating on iterators, as in the other overload, this function +operates on the specified \a container to obtain the number of instances +of \a value in the variable passed as a reference in argument \a n. +*/ + +/*! \fn void qSwap(T &var1, T &var2) + \relates + + Exchanges the values of variables \a var1 and \a var2. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using the quicksort algorithm. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + \sa qStableSort(), {random access iterators} +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + An alternative to using qSort() is to put the items to sort in a + QMap, using the sort key as the QMap key. This is often more + convenient than defining a \a lessThan function. For example, the + following code shows how to sort a list of strings case + insensitively using QMap: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 + + \sa QMap +*/ + +/*! \fn void qSort(Container &container) + \relates + + \overload + + This is the same as qSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using a stable sorting algorithm. + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + \sa qSort(), {random access iterators} +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 + + Note that earlier versions of Qt allowed using a lessThan function that took its + arguments by non-const reference. From 4.3 and on this is no longer possible, + the arguments has to be passed by const reference or value. + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. +*/ + +/*! + \fn void qStableSort(Container &container) + \relates + + \overload + + This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the first ocurrence of \a value. If no + such item is found, returns the position where it should be + inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qLowerBound() can be used in conjunction with qUpperBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 + + \sa qUpperBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qLowerBound(const Container &container, const T &value) + \relates + + \overload + + For read-only iteration over containers, this function is broadly equivalent to + qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it + returns a const iterator, you cannot use it to modify the container; for example, + to insert items. +*/ + +/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the one-past-the-last occurrence of \a + value. If no such item is found, returns the position where the + item should be inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qUpperBound() can be used in conjunction with qLowerBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 + + \sa qLowerBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qUpperBound(const Container &container, const T &value) + \relates + + \overload + + This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of an occurrence of \a value. If there are + no occurrences of \a value, returns \a end. + + The items in the range [\a begin, \a end) must be sorted in + ascending order; see qSort(). + + If there are many occurrences of the same value, any one of them + could be returned. Use qLowerBound() or qUpperBound() if you need + finer control. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 + + This function requires the item type (in the example above, + QString) to implement \c operator<(). + + See the \l{#binaryFind example}{detailed + description} for an example usage. + + \sa qLowerBound(), qUpperBound(), {random access iterators} +*/ + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qBinaryFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! + \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) + \relates + + Deletes all the items in the range [\a begin, \a end) using the + C++ \c delete operator. The item type must be a pointer type (for + example, \c{QWidget *}). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 + + Notice that qDeleteAll() doesn't remove the items from the + container; it merely calls \c delete on them. In the example + above, we call clear() on the container to remove the items. + + This function can also be used to delete items stored in + associative containers, such as QMap and QHash. Only the objects + stored in each container will be deleted by this function; objects + used as keys will not be deleted. + + \sa {forward iterators} +*/ + +/*! + \fn void qDeleteAll(const Container &c) + \relates + + \overload + + This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). +*/ + +/*! \fn LessThan qLess() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 + + \sa {qGreater()}{qGreater()} +*/ + +/*! \fn LessThan qGreater() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 + + \sa {qLess()}{qLess()} +*/ diff --git a/doc/src/classes/qcache.qdoc b/doc/src/classes/qcache.qdoc new file mode 100644 index 0000000..6c88ede --- /dev/null +++ b/doc/src/classes/qcache.qdoc @@ -0,0 +1,244 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QCache + \brief The QCache class is a template class that provides a cache. + + \ingroup tools + \ingroup shared + \mainclass + \reentrant + + QCache\ defines a cache that stores objects of type T + associated with keys of type Key. For example, here's the + definition of a cache that stores objects of type Employee + associated with an integer key: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 + + Here's how to insert an object in the cache: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 + + The advantage of using QCache over some other key-based data + structure (such as QMap or QHash) is that QCache automatically + takes ownership of the objects that are inserted into the cache and + deletes them to make room for new objects, if necessary. When + inserting an object into the cache, you can specify a \e{cost}, + which should bear some approximate relationship to the amount of + memory taken by the object. When the sum of all objects' costs + (totalCost()) exceeds the cache's limit (maxCost()), QCache starts + deleting objects in the cache to keep under the limit, starting with + less recently accessed objects. + + By default, QCache's maxCost() is 100. You can specify a + different value in the QCache constructor: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 + + Each time you call insert(), you can specify a cost as third + argument (after the key and a pointer to the object to insert). + After the call, the inserted object is owned by the QCache, which + may delete it at any time to make room for other objects. + + To look up objects in the cache, use object() or + operator[](). This function looks up an object by its key, and + returns either a pointer to the cached object (which is owned by + the cache) or 0. + + If you want to remove an object from the cache for a particular key, + call remove(). This will also delete the object. If you want to + remove an object from the cache without the QCache deleting it, use + take(). + + \sa QPixmapCache, QHash, QMap +*/ + +/*! \fn QCache::QCache(int maxCost = 100) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost. +*/ + +/*! \fn QCache::~QCache() + + Destroys the cache. Deletes all the objects in the cache. +*/ + +/*! \fn int QCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost(), totalCost() +*/ + +/*! \fn void QCache::setMaxCost(int cost) + + Sets the maximum allowed total cost of the cache to \a cost. If + the current total cost is greater than \a cost, some objects are + deleted immediately. + + \sa maxCost(), totalCost() +*/ + +/*! \fn int QCache::totalCost() const + + Returns the total cost of the objects in the cache. + + This value is normally below maxCost(), but QCache makes an + exception for Qt's \l{implicitly shared} classes. If a cached + object shares its internal data with another instance, QCache may + keep the object lying around, possibly contributing to making + totalCost() larger than maxCost(). + + \sa setMaxCost() +*/ + +/*! \fn int QCache::size() const + + Returns the number of objects in the cache. + + \sa isEmpty() +*/ + +/*! \fn int QCache::count() const + + Same as size(). +*/ + +/*! \fn bool QCache::isEmpty() const + + Returns true if the cache contains no objects; otherwise + returns false. + + \sa size() +*/ + +/*! \fn QList QCache::keys() const + + Returns a list of the keys in the cache. +*/ + +/*! \fn void QCache::clear(); + + Deletes all the objects in the cache. + + \sa remove(), take() +*/ + + +/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1) + + Inserts \a object into the cache with key \a key and + associated cost \a cost. Any object with the same key already in + the cache will be removed. + + After this call, \a object is owned by the QCache and may be + deleted at any time. In particular, if \a cost is greater than + maxCost(), the object will be deleted immediately. + + The function returns true if the object was inserted into the + cache; otherwise it returns false. + + \sa take(), remove() +*/ + +/*! \fn T *QCache::object(const Key &key) const + + Returns the object associated with key \a key, or 0 if the key does + not exist in the cache. + + \warning The returned object is owned by QCache and may be + deleted at any time. + + \sa take(), remove() +*/ + +/*! \fn bool QCache::contains(const Key &key) const + + Returns true if the cache contains an object associated with key \a + key; otherwise returns false. + + \sa take(), remove() +*/ + +/*! \fn T *QCache::operator[](const Key &key) const + + Returns the object associated with key \a key, or 0 if the key does + not exist in the cache. + + This is the same as object(). + + \warning The returned object is owned by QCache and may be + deleted at any time. +*/ + +/*! \fn bool QCache::remove(const Key &key) + + Deletes the object associated with key \a key. Returns true if the + object was found in the cache; otherwise returns false. + + \sa take(), clear() +*/ + +/*! \fn T *QCache::take(const Key &key) + + Takes the object associated with key \a key out of the cache + without deleting it. Returns a pointer to the object taken out, or + 0 if the key does not exist in the cache. + + The ownership of the returned object is passed to the caller. + + \sa remove() +*/ + +/*! + \fn QCache::QCache(int maxCost, int dummy) + + Use QCache(int) instead. +*/ + +/*! + \fn T *QCache::find(const Key &key) const + + Use object() instead. +*/ diff --git a/doc/src/classes/qcolormap.qdoc b/doc/src/classes/qcolormap.qdoc new file mode 100644 index 0000000..95f7dc0 --- /dev/null +++ b/doc/src/classes/qcolormap.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QColormap + \ingroup multimedia + + \brief The QColormap class maps device independent QColors to device + dependent pixel values. +*/ + +/*! \enum QColormap::Mode + + This enum describes how QColormap maps device independent RGB + values to device dependent pixel values. + + \value Direct Pixel values are derived directly from the RGB + values, also known as "True Color." + + \value Indexed Pixel values represent indexes into a vector of + available colors, i.e. QColormap uses the index of the color that + most closely matches an RGB value. + + \value Gray Similar to \c Indexed, pixel values represent a vector + of available gray tones. QColormap uses the index of the gray + tone that most closely matches the computed gray tone of an RGB + value. +*/ + +/*! + \fn QColormap QColormap::instance(int screen) + + Returns the colormap for the specified \a screen. If \a screen is + -1, this function returns the colormap for the default screen. +*/ + +/*! + \fn QColormap::QColormap(const QColormap &colormap) + + Constructs a copy of another \a colormap. +*/ + +/*! + \fn QColormap::~QColormap() + + Destroys the colormap. +*/ + +/*! + \fn int QColormap::size() const + + Returns the size of the colormap for \c Indexed and \c Gray modes; + Returns -1 for \c Direct mode. + + \sa colormap() +*/ + +/*! + \fn uint QColormap::pixel(const QColor &color) const + + Returns a device dependent pixel value for the \a color. + + \sa colorAt() +*/ + +/*! + \fn int QColormap::depth() const + + Returns the depth of the device. + + \sa size() +*/ + +/*! + \fn QColormap::Mode QColormap::mode() const + + Returns the mode of this colormap. + + \sa QColormap::Mode +*/ + +/*! + \fn const QColor QColormap::colorAt(uint pixel) const + + Returns a QColor for the \a pixel. + + \sa pixel() +*/ + +/*! + \fn const QVector QColormap::colormap() const + + Returns a vector of colors which represents the devices colormap + for \c Indexed and \c Gray modes. This function returns an empty + vector for \c Direct mode. + + \sa size() +*/ + +/*! \fn HPALETTE QColormap::hPal() + + This function is only available on Windows. + + Returns an handle to the HPALETTE used by this colormap. If no + HPALETTE is being used, this function returns zero. +*/ + +/*! \since 4.2 + + \fn QColormap &QColormap::operator=(const QColormap &colormap) + + Assigns the given \a colormap to \e this color map and returns + a reference to \e this color map. +*/ diff --git a/doc/src/classes/qdesktopwidget.qdoc b/doc/src/classes/qdesktopwidget.qdoc new file mode 100644 index 0000000..56a882d --- /dev/null +++ b/doc/src/classes/qdesktopwidget.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QDesktopWidget + \brief The QDesktopWidget class provides access to screen information on multi-head systems. + + \ingroup advanced + \ingroup desktop + \ingroup environment + \mainclass + + QApplication::desktop() function should be used to get an instance + of the QDesktopWidget. + + Systems with more than one graphics card and monitor can manage the + physical screen space available either as multiple desktops, or as a + large virtual desktop, which usually has the size of the bounding + rectangle of all the screens (see virtualDesktop). For an + application, one of the available screens is the primary screen, i.e. + the screen where the main widget resides (see primaryScreen). All + windows opened in the context of the application should be + constrained to the boundaries of the primary screen; for example, + it would be inconvenient if a dialog box popped up on a different + screen, or split over two screens. + + The QDesktopWidget provides information about the geometry of the + available screens with screenGeometry(). The number of screens + available is returned by screenCount, and the screenCountChanged + signal is emitted when screens are added or removed during runtime. + The screen number that a particular point or widget is located in + is returned by screenNumber(). + + Widgets provided by Qt use this class, for example, to place + tooltips, menus and dialog boxes according to the parent or + application widget. Applications can use this class to save window + positions, or to place child widgets and dialogs on one particular + screen. + + \img qdesktopwidget.png Managing Multiple Screens + + In the illustration above, Application One's primary screen is + screen 0, and App Two's primary screen is screen 1. + + \target multiple screens note + \note QDesktopWidget inherits the QWidget properties, width() and + height(), which specify the size of the desktop. However, for + desktops with multiple screens, the size of the desktop is the union + of all the screen sizes, so width() and height() should \e not be + used for computing the size of a widget to be placed on one of the + screens. The correct width and height values are obtained using + availableGeometry() or screenGeometry() for a particular screen. + + \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() +*/ + +/*! + \fn QDesktopWidget::QDesktopWidget() + + \internal + + Creates the desktop widget. + + If the system supports a virtual desktop, this widget will have + the size of the virtual desktop; otherwise this widget will have + the size of the primary screen. + + Instead of using QDesktopWidget directly, use QApplication::desktop(). +*/ + +/*! + \fn QDesktopWidget::~QDesktopWidget() + + \internal + + Destroys the desktop widget and frees any allocated resources. +*/ + +/*! + \fn int QDesktopWidget::numScreens() const + + Returns the number of available screens. + + \obsolete + + This function is deprecated. Use screenCount instead. + + \sa primaryScreen +*/ + +/*! + \fn QWidget *QDesktopWidget::screen(int screen) + + Returns a widget that represents the screen with index \a screen + (a value of -1 means the default screen). + + If the system uses a virtual desktop, the returned widget will + have the geometry of the entire virtual desktop; i.e., bounding + every \a screen. + + \sa primaryScreen, screenCount, virtualDesktop +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(int screen) const + + Returns the available geometry of the screen with index \a screen. What + is available will be subrect of screenGeometry() based on what the + platform decides is available (for example excludes the dock and menu bar + on Mac OS X, or the task bar on Windows). The default screen is used if + \a screen is -1. + + \sa screenNumber(), screenGeometry() +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const + \overload + + Returns the available geometry of the screen which contains \a widget. + + \sa screenGeometry() +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const + \overload + + Returns the available geometry of the screen which contains \a p. + + \sa screenGeometry() +*/ + + +/*! + \fn const QRect QDesktopWidget::screenGeometry(int screen) const + + Returns the geometry of the screen with index \a screen. The default + screen is used if \a screen is -1. + + \sa screenNumber() +*/ + +/*! + \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const + \overload + + Returns the geometry of the screen which contains \a widget. +*/ + +/*! + \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const + \overload + + Returns the geometry of the screen which contains \a p. +*/ + + +/*! + \fn int QDesktopWidget::screenNumber(const QWidget *widget) const + + Returns the index of the screen that contains the largest + part of \a widget, or -1 if the widget not on a screen. + + \sa primaryScreen +*/ + +/*! + \fn int QDesktopWidget::screenNumber(const QPoint &point) const + + \overload + Returns the index of the screen that contains the \a point, or the + screen which is the shortest distance from the \a point. + + \sa primaryScreen +*/ + +/*! + \fn void QDesktopWidget::resizeEvent(QResizeEvent *event) + \reimp +*/ + +/*! + \fn void QDesktopWidget::resized(int screen) + + This signal is emitted when the size of \a screen changes. +*/ + +/*! + \fn void QDesktopWidget::workAreaResized(int screen) + + This signal is emitted when the work area available on \a screen changes. +*/ + +/*! + \property QDesktopWidget::screenCount + \brief the number of screens currently available on the system. + + \since 4.6 + + \sa screenCountChanged() +*/ + +/*! + \property QDesktopWidget::primaryScreen + \brief the index of the screen that is configured to be the primary screen + on the system. +*/ + +/*! + \property QDesktopWidget::virtualDesktop + + \brief if the system manages the available screens in a virtual desktop. + + For virtual desktops, screen() will always return the same widget. + The size of the virtual desktop is the size of this desktop + widget. +*/ + +/*! + \fn void QDesktopWidget::screenCountChanged(int newCount) + + \since 4.6 + + This signal is emitted when the number of screens changes to \a newCount. + + \sa screenCount +*/ diff --git a/doc/src/classes/qiterator.qdoc b/doc/src/classes/qiterator.qdoc new file mode 100644 index 0000000..416b4bc --- /dev/null +++ b/doc/src/classes/qiterator.qdoc @@ -0,0 +1,1431 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QListIterator + \inmodule QtCore + + \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. + + QList has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QList member functions take an index as their first parameter, + making it possible to access, modify, and remove items without + using iterators. + + QListIterator\ allows you to iterate over a QList\ (or a + QQueue\). If you want to modify the list as you iterate over + it, use QMutableListIterator\ instead. + + The QListIterator constructor takes a QList as argument. After + construction, the iterator is located at the very beginning of + the list (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, and returns the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same list. If the list is + modified while a QListIterator is active, the QListIterator will + continue iterating over the original list, ignoring the modified + copy. + + \sa QMutableListIterator, QList::const_iterator +*/ + +/*! + \class QLinkedListIterator + \inmodule QtCore + + \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList. + + QLinkedList has both \l{Java-style iterators} and + \l{STL-style iterators}. The Java-style iterators are more + high-level and easier to use than the STL-style iterators; on the + other hand, they are slightly less efficient. + + QLinkedListIterator\ allows you to iterate over a + QLinkedList\. If you want to modify the list as you iterate + over it, use QMutableLinkedListIterator\ instead. + + The QLinkedListIterator constructor takes a QLinkedList as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, and returns the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same list. If the list is + modified while a QLinkedListIterator is active, the + QLinkedListIterator will continue iterating over the original + list, ignoring the modified copy. + + \sa QMutableLinkedListIterator, QLinkedList::const_iterator +*/ + +/*! + \class QVectorIterator + \inmodule QtCore + \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack. + + QVector has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QVector member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QVectorIterator\ allows you to iterate over a QVector\ + (or a QStack\). If you want to modify the vector as you + iterate over it, use QMutableVectorIterator\ instead. + + The QVectorIterator constructor takes a QVector as argument. + After construction, the iterator is located at the very beginning + of the vector (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 + + The next() function returns the next item in the vector and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same vector. If the vector + is modified while a QVectorIterator is active, the QVectorIterator + will continue iterating over the original vector, ignoring the + modified copy. + + \sa QMutableVectorIterator, QVector::const_iterator +*/ + +/*! + \class QSetIterator + \inmodule QtCore + \brief The QSetIterator class provides a Java-style const iterator for QSet. + + QSet supports both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QSetIterator\ allows you to iterate over a QSet\. If you + want to modify the set as you iterate over it, use + QMutableSetIterator\ instead. + + The constructor takes a QSet as argument. After construction, the + iterator is located at the very beginning of the set (before + the first item). Here's how to iterate over all the elements + sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 + + The next() function returns the next item in the set and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same set. If the set + is modified while a QSetIterator is active, the QSetIterator + will continue iterating over the original set, ignoring the + modified copy. + + \sa QMutableSetIterator, QSet::const_iterator +*/ + +/*! + \class QMutableListIterator + \inmodule QtCore + + \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue. + + QList has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QList member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QMutableListIterator\ allows you to iterate over a QList\ + (or a QQueue\) and modify the list. If you don't want to + modify the list (or have a const QList), use the slightly faster + QListIterator\ instead. + + The QMutableListIterator constructor takes a QList as argument. + After construction, the iterator is located at the very beginning + of the list (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the list, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the list, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 + + The example traverses a list, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given list at any + time. Furthermore, no changes should be done directly to the list + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QListIterator, QList::iterator +*/ + +/*! + \class QMutableLinkedListIterator + \inmodule QtCore + + \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList. + + QLinkedList has both \l{Java-style iterators} and + \l{STL-style iterators}. The Java-style iterators are more + high-level and easier to use than the STL-style iterators; on the + other hand, they are slightly less efficient. + + QMutableLinkedListIterator\ allows you to iterate over a + QLinkedList\ and modify the list. If you don't want to modify + the list (or have a const QLinkedList), use the slightly faster + QLinkedListIterator\ instead. + + The QMutableLinkedListIterator constructor takes a QLinkedList as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the list, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the list, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 + + The example traverses a list, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given list at any + time. Furthermore, no changes should be done directly to the list + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QLinkedListIterator, QLinkedList::iterator +*/ + +/*! + \class QMutableVectorIterator + \inmodule QtCore + + \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack. + + QVector has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QVector member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QMutableVectorIterator\ allows you to iterate over a + QVector\ and modify the vector. If you don't want to modify + the vector (or have a const QVector), use the slightly faster + QVectorIterator\ instead. + + The QMutableVectorIterator constructor takes a QVector as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 + + The next() function returns the next item in the vector and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the vector, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the vector, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 + + The example traverses a vector, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given vector at any + time. Furthermore, no changes should be done directly to the + vector while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QVectorIterator, QVector::iterator +*/ + +/*! + \class QMutableSetIterator + \inmodule QtCore + \since 4.2 + + \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. + + QSet has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableSetIterator\ allows you to iterate over a QSet\ + and remove items from the set as you iterate. If you don't want + to modify the set (or have a const QSet), use the slightly faster + QSetIterator\ instead. + + The QMutableSetIterator constructor takes a QSet as argument. + After construction, the iterator is located at the very beginning + of the set (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 + + The next() function returns the next item in the set and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 + + If you want to remove items as you iterate over the set, use + remove(). + + Only one mutable iterator can be active on a given set at any + time. Furthermore, no changes should be done directly to the set + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QSetIterator, QSet::iterator +*/ + +/*! + \fn QListIterator::QListIterator(const QList &list) + \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList &list) + \fn QMutableListIterator::QMutableListIterator(QList &list) + \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList &list) + + Constructs an iterator for traversing \a list. The iterator is + set to be at the front of the list (before the first item). + + \sa operator=() +*/ + +/*! + \fn QVectorIterator::QVectorIterator(const QVector &vector) + \fn QMutableVectorIterator::QMutableVectorIterator(QVector &vector) + + Constructs an iterator for traversing \a vector. The iterator is + set to be at the front of the vector (before the first item). + + \sa operator=() +*/ + +/*! + \fn QSetIterator::QSetIterator(const QSet &set) + \fn QMutableSetIterator::QMutableSetIterator(QSet &set) + + Constructs an iterator for traversing \a set. The iterator is + set to be at the front of the set (before the first item). + + \sa operator=() +*/ + +/*! + \fn QMutableListIterator::~QMutableListIterator() + \fn QMutableLinkedListIterator::~QMutableLinkedListIterator() + \fn QMutableVectorIterator::~QMutableVectorIterator() + \fn QMutableSetIterator::~QMutableSetIterator() + + Destroys the iterator. + + \sa operator=() +*/ + +/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList &list) + \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList &list) + \fn QListIterator &QListIterator::operator=(const QList &list) + \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList &list) + + Makes the iterator operate on \a list. The iterator is set to be + at the front of the list (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector &vector) + \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector &vector) + + Makes the iterator operate on \a vector. The iterator is set to be + at the front of the vector (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QSetIterator &QSetIterator::operator=(const QSet &set) + \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet &set) + + Makes the iterator operate on \a set. The iterator is set to be + at the front of the set (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn void QListIterator::toFront() + \fn void QLinkedListIterator::toFront() + \fn void QVectorIterator::toFront() + \fn void QSetIterator::toFront() + \fn void QMutableListIterator::toFront() + \fn void QMutableLinkedListIterator::toFront() + \fn void QMutableVectorIterator::toFront() + \fn void QMutableSetIterator::toFront() + + Moves the iterator to the front of the container (before the + first item). + + \sa toBack(), next() +*/ + +/*! \fn void QListIterator::toBack() + \fn void QLinkedListIterator::toBack() + \fn void QVectorIterator::toBack() + \fn void QSetIterator::toBack() + \fn void QMutableListIterator::toBack() + \fn void QMutableLinkedListIterator::toBack() + \fn void QMutableVectorIterator::toBack() + \fn void QMutableSetIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront(), previous() +*/ + +/*! \fn bool QListIterator::hasNext() const + \fn bool QLinkedListIterator::hasNext() const + \fn bool QVectorIterator::hasNext() const + \fn bool QSetIterator::hasNext() const + \fn bool QMutableListIterator::hasNext() const + \fn bool QMutableLinkedListIterator::hasNext() const + \fn bool QMutableVectorIterator::hasNext() const + \fn bool QMutableSetIterator::hasNext() const + + Returns true if there is at least one item ahead of the iterator, + i.e. the iterator is \e not at the back of the container; + otherwise returns false. + + \sa hasPrevious(), next() +*/ + +/*! \fn const T &QListIterator::next() + \fn const T &QLinkedListIterator::next() + \fn const T &QVectorIterator::next() + \fn const T &QSetIterator::next() + \fn const T &QMutableSetIterator::next() + + Returns the next item and advances the iterator by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn T &QMutableListIterator::next() + \fn T &QMutableLinkedListIterator::next() + \fn T &QMutableVectorIterator::next() + + Returns a reference to the next item, and advances the iterator + by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn const T &QListIterator::peekNext() const + \fn const T &QLinkedListIterator::peekNext() const + \fn const T &QVectorIterator::peekNext() const + \fn const T &QSetIterator::peekNext() const + \fn const T &QMutableSetIterator::peekNext() const + + Returns the next item without moving the iterator. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn T &QMutableListIterator::peekNext() const + \fn T &QMutableLinkedListIterator::peekNext() const + \fn T &QMutableVectorIterator::peekNext() const + + Returns a reference to the next item, without moving the iterator. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn bool QListIterator::hasPrevious() const + \fn bool QLinkedListIterator::hasPrevious() const + \fn bool QVectorIterator::hasPrevious() const + \fn bool QSetIterator::hasPrevious() const + \fn bool QMutableListIterator::hasPrevious() const + \fn bool QMutableLinkedListIterator::hasPrevious() const + \fn bool QMutableVectorIterator::hasPrevious() const + \fn bool QMutableSetIterator::hasPrevious() const + + Returns true if there is at least one item behind the iterator, + i.e. the iterator is \e not at the front of the container; + otherwise returns false. + + \sa hasNext(), previous() +*/ + +/*! \fn const T &QListIterator::previous() + \fn const T &QLinkedListIterator::previous() + \fn const T &QVectorIterator::previous() + \fn const T &QSetIterator::previous() + \fn const T &QMutableSetIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn T &QMutableListIterator::previous() + \fn T &QMutableLinkedListIterator::previous() + \fn T &QMutableVectorIterator::previous() + + Returns a reference to the previous item and moves the iterator + back by one position. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn const T &QListIterator::peekPrevious() const + \fn const T &QLinkedListIterator::peekPrevious() const + \fn const T &QVectorIterator::peekPrevious() const + \fn const T &QSetIterator::peekPrevious() const + \fn const T &QMutableSetIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn T &QMutableListIterator::peekPrevious() const + \fn T &QMutableLinkedListIterator::peekPrevious() const + \fn T &QMutableVectorIterator::peekPrevious() const + + Returns a reference to the previous item, without moving the iterator. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn bool QListIterator::findNext(const T &value) + \fn bool QLinkedListIterator::findNext(const T &value) + \fn bool QVectorIterator::findNext(const T &value) + \fn bool QSetIterator::findNext(const T &value) + \fn bool QMutableListIterator::findNext(const T &value) + \fn bool QMutableLinkedListIterator::findNext(const T &value) + \fn bool QMutableVectorIterator::findNext(const T &value) + \fn bool QMutableSetIterator::findNext(const T &value) + + Searches for \a value starting from the current iterator position + forward. Returns true if \a value is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just after the matching item; otherwise, the iterator is + positioned at the back of the container. + + \sa findPrevious() +*/ + +/*! \fn bool QListIterator::findPrevious(const T &value) + \fn bool QLinkedListIterator::findPrevious(const T &value) + \fn bool QVectorIterator::findPrevious(const T &value) + \fn bool QSetIterator::findPrevious(const T &value) + \fn bool QMutableListIterator::findPrevious(const T &value) + \fn bool QMutableLinkedListIterator::findPrevious(const T &value) + \fn bool QMutableVectorIterator::findPrevious(const T &value) + \fn bool QMutableSetIterator::findPrevious(const T &value) + + Searches for \a value starting from the current iterator position + backward. Returns true if \a value is found; otherwise returns + false. + + After the call, if \a value was found, the iterator is positioned + just before the matching item; otherwise, the iterator is + positioned at the front of the container. + + \sa findNext() +*/ + +/*! \fn void QMutableListIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableLinkedListIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableVectorIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableSetIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 + + \sa value() +*/ + +/*! \fn void QMutableListIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 + + \sa value(), remove(), insert() +*/ + +/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 + + \sa value(), remove(), insert() +*/ + +/*! \fn void QMutableVectorIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 + + \sa value(), remove(), insert() +*/ + +/*! \fn const T &QMutableListIterator::value() const + \fn const T &QMutableLinkedListIterator::value() const + \fn const T &QMutableVectorIterator::value() const + \fn const T &QMutableSetIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is equivalent to + peekPrevious(). After a call to previous() or findPrevious(), value() is + equivalent to peekNext(). +*/ + +/*! + \fn T &QMutableListIterator::value() + \fn T &QMutableLinkedListIterator::value() + \fn T &QMutableVectorIterator::value() + \overload + + Returns a non-const reference to the value of the last item that + was jumped over using one of the traversal functions. +*/ + +/*! \fn void QMutableListIterator::insert(const T &value) + \fn void QMutableLinkedListIterator::insert(const T &value) + \fn void QMutableVectorIterator::insert(const T &value) + + Inserts \a value at the current iterator position. After the + call, the iterator is located just after the inserted item. + + \sa remove(), setValue() +*/ + +/*! + \class QMapIterator + \inmodule QtCore + + \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. + + QMap has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMapIterator\ allows you to iterate over a QMap (or a + QMultiMap). If you want to modify the map as you iterate over + it, use QMutableMapIterator instead. + + The QMapIterator constructor takes a QMap as argument. After + construction, the iterator is located at the very beginning of + the map (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 + + Multiple iterators can be used on the same map. If the map is + modified while a QMapIterator is active, the QMapIterator will + continue iterating over the original map, ignoring the modified + copy. + + \sa QMutableMapIterator, QMap::const_iterator +*/ + +/*! + \class QHashIterator + \inmodule QtCore + + \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. + + QHash has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QHashIterator\ allows you to iterate over a QHash (or a + QMultiHash). If you want to modify the hash as you iterate over + it, use QMutableHashIterator instead. + + The QHashIterator constructor takes a QHash as argument. After + construction, the iterator is located at the very beginning of + the hash (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 + + The next() function returns the next item in the hash and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 + + Multiple iterators can be used on the same hash. If the hash is + modified while a QHashIterator is active, the QHashIterator will + continue iterating over the original hash, ignoring the modified + copy. + + \sa QMutableHashIterator, QHash::const_iterator +*/ + +/*! + \class QMutableMapIterator + \inmodule QtCore + + \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. + + QMap has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableMapIterator\ allows you to iterate over a QMap + (or a QMultiMap) and modify the map. If you don't want to modify + the map (or have a const QMap), use the slightly faster + QMapIterator instead. + + The QMutableMapIterator constructor takes a QMap as argument. + After construction, the iterator is located at the very beginning + of the map (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 + + If you want to remove items as you iterate over the map, use + remove(). If you want to modify the value of an item, use + setValue(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 + + The example removes all (key, value) pairs where the key and the + value are the same. + + Only one mutable iterator can be active on a given map at any + time. Furthermore, no changes should be done directly to the map + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QMapIterator, QMap::iterator +*/ + +/*! + \class QMutableHashIterator + \inmodule QtCore + + \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. + + QHash has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableHashIterator\ allows you to iterate over a QHash + (or a QMultiHash) and modify the hash. If you don't want to modify + the hash (or have a const QHash), use the slightly faster + QHashIterator instead. + + The QMutableHashIterator constructor takes a QHash as argument. + After construction, the iterator is located at the very beginning + of the hash (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 + + The next() function returns the next item in the hash and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 + + If you want to remove items as you iterate over the hash, use + remove(). If you want to modify the value of an item, use + setValue(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 + + The example removes all (key, value) pairs where the key and the + value are the same. + + Only one mutable iterator can be active on a given hash at any + time. Furthermore, no changes should be done directly to the hash + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QHashIterator, QHash::iterator +*/ + +/*! \fn QMapIterator::QMapIterator(const QMap &map) + \fn QMutableMapIterator::QMutableMapIterator(QMap &map) + + Constructs an iterator for traversing \a map. The iterator is set + to be at the front of the map (before the first item). + + \sa operator=() +*/ + +/*! \fn QHashIterator::QHashIterator(const QHash &hash) + \fn QMutableHashIterator::QMutableHashIterator(QHash &hash) + + Constructs an iterator for traversing \a hash. The iterator is + set to be at the front of the hash (before the first item). + + \sa operator=() +*/ + +/*! + \fn QMutableMapIterator::~QMutableMapIterator() + \fn QMutableHashIterator::~QMutableHashIterator() + + Destroys the iterator. + + \sa operator=() +*/ + +/*! \fn QMapIterator &QMapIterator::operator=(const QMap &map) + \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap &map) + + Makes the iterator operate on \a map. The iterator is set to be + at the front of the map (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QHashIterator &QHashIterator::operator=(const QHash &hash) + \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash &hash) + + Makes the iterator operate on \a hash. The iterator is set to be + at the front of the hash (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn void QMapIterator::toFront() + \fn void QHashIterator::toFront() + \fn void QMutableMapIterator::toFront() + \fn void QMutableHashIterator::toFront() + + Moves the iterator to the front of the container (before the + first item). + + \sa toBack(), next() +*/ + +/*! \fn void QMapIterator::toBack() + \fn void QHashIterator::toBack() + \fn void QMutableMapIterator::toBack() + \fn void QMutableHashIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront(), previous() +*/ + +/*! \fn bool QMapIterator::hasNext() const + \fn bool QHashIterator::hasNext() const + \fn bool QMutableMapIterator::hasNext() const + \fn bool QMutableHashIterator::hasNext() const + + Returns true if there is at least one item ahead of the iterator, + i.e. the iterator is \e not at the back of the container; + otherwise returns false. + + \sa hasPrevious(), next() +*/ + +/*! \fn QMapIterator::Item QMapIterator::next() + \fn QHashIterator::Item QHashIterator::next() + + Returns the next item and advances the iterator by one position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::next() + \fn QMutableHashIterator::Item QMutableHashIterator::next() + + Returns the next item and advances the iterator by one position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn QMapIterator::Item QMapIterator::peekNext() const + \fn QHashIterator::Item QHashIterator::peekNext() const + + Returns the next item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const + \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const + + Returns a reference to the next item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn bool QMapIterator::hasPrevious() const + \fn bool QHashIterator::hasPrevious() const + \fn bool QMutableMapIterator::hasPrevious() const + \fn bool QMutableHashIterator::hasPrevious() const + + Returns true if there is at least one item behind the iterator, + i.e. the iterator is \e not at the front of the container; + otherwise returns false. + + \sa hasNext(), previous() +*/ + +/*! \fn QMapIterator::Item QMapIterator::previous() + \fn QHashIterator::Item QHashIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous() + \fn QMutableHashIterator::Item QMutableHashIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const + \fn QHashIterator::Item QHashIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const + \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn const T &QMapIterator::value() const + \fn const T &QHashIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is + equivalent to peekPrevious().value(). After a call to previous() + or findPrevious(), value() is equivalent to peekNext().value(). + + \sa key() +*/ + +/*! + \fn const T &QMutableMapIterator::value() const + \fn const T &QMutableHashIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is + equivalent to peekPrevious().value(). After a call to previous() + or findPrevious(), value() is equivalent to peekNext().value(). + + \sa key(), setValue() +*/ + +/*! + \fn T &QMutableMapIterator::value() + \fn T &QMutableHashIterator::value() + \overload + + Returns a non-const reference to the value of + the last item that was jumped over using one + of the traversal functions. +*/ + +/*! \fn const Key &QMapIterator::key() const + \fn const Key &QHashIterator::key() const + \fn const Key &QMutableMapIterator::key() const + \fn const Key &QMutableHashIterator::key() const + + Returns the key of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), key() is + equivalent to peekPrevious().key(). After a call to previous() or + findPrevious(), key() is equivalent to peekNext().key(). + + \sa value() +*/ + +/*! \fn bool QMapIterator::findNext(const T &value) + \fn bool QHashIterator::findNext(const T &value) + \fn bool QMutableMapIterator::findNext(const T &value) + \fn bool QMutableHashIterator::findNext(const T &value) + + Searches for \a value starting from the current iterator position + forward. Returns true if a (key, value) pair with value \a value + is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just after the matching item; otherwise, the iterator is + positioned at the back of the container. + + \sa findPrevious() +*/ + +/*! \fn bool QMapIterator::findPrevious(const T &value) + \fn bool QHashIterator::findPrevious(const T &value) + \fn bool QMutableMapIterator::findPrevious(const T &value) + \fn bool QMutableHashIterator::findPrevious(const T &value) + + Searches for \a value starting from the current iterator position + backward. Returns true if a (key, value) pair with value \a value + is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just before the matching item; otherwise, the iterator is + positioned at the front of the container. + + \sa findNext() +*/ + +/*! \fn void QMutableMapIterator::remove() + \fn void QMutableHashIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + \sa setValue() +*/ + +/*! \fn void QMutableMapIterator::setValue(const T &value) + \fn void QMutableHashIterator::setValue(const T &value) + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + \sa key(), value(), remove() +*/ diff --git a/doc/src/classes/qmacstyle.qdoc b/doc/src/classes/qmacstyle.qdoc new file mode 100644 index 0000000..ae2d95b --- /dev/null +++ b/doc/src/classes/qmacstyle.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \class QMacStyle + \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. + + \ingroup appearance + + This class is implemented as a wrapper to the HITheme + APIs, allowing applications to be styled according to the current + theme in use on Mac OS X. This is done by having primitives + in QStyle implemented in terms of what Mac OS X would normally theme. + + \warning This style is only available on Mac OS X because it relies on the + HITheme APIs. + + There are additional issues that should be taken + into consideration to make an application compatible with the + \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html + Apple Human Interface Guidelines \endlink. Some of these issues are outlined + below. + + \list + + \i Layout - The restrictions on window layout are such that some + aspects of layout that are style-dependent cannot be achieved + using QLayout. Changes are being considered (and feedback would be + appreciated) to make layouts QStyle-able. Some of the restrictions + involve horizontal and vertical widget alignment and widget size + (covered below). + + \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt + does not fully implement this behavior so as to maintain cross-platform + compatibility. As a result some widgets sizes may be inappropriate (and + subsequently not rendered correctly by the HITheme APIs).The + QWidget::sizeHint() will return the appropriate size for many + managed widgets (widgets enumerated in \l QStyle::ContentsType). + + \i Effects - QMacStyle uses HITheme for performing most of the drawing, but + also uses emulation in a few cases where HITheme does not provide the + required functionality (for example, tab bars on Panther, the toolbar + separator, etc). We tried to make the emulation as close to the original as + possible. Please report any issues you see in effects or non-standard + widgets. + + \endlist + + There are other issues that need to be considered in the feel of + your application (including the general color scheme to match the + Aqua colors). The Guidelines mentioned above will remain current + with new advances and design suggestions for Mac OS X. + + Note that the functions provided by QMacStyle are + reimplementations of QStyle functions; see QStyle for their + documentation. + + \img qmacstyle.png + \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle +*/ + + +/*! + \enum QMacStyle::WidgetSizePolicy + + \value SizeSmall + \value SizeLarge + \value SizeMini + \value SizeDefault + \omitvalue SizeNone +*/ + +/*! \fn QMacStyle::QMacStyle() + Constructs a QMacStyle object. +*/ + +/*! \fn QMacStyle::~QMacStyle() + Destructs a QMacStyle object. +*/ + +/*! \fn void QMacStyle::polish(QPalette &pal) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QWidget* w) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QWidget* w) + \reimp +*/ + +/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QPalette QMacStyle::standardPalette() const + \reimp +*/ + +/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! + \enum QMacStyle::FocusRectPolicy + + This type is used to signify a widget's focus rectangle policy. + + \value FocusEnabled show a focus rectangle when the widget has focus. + \value FocusDisabled never show a focus rectangle for the widget. + \value FocusDefault show a focus rectangle when the widget has + focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, + QListBox, QListView, editable QTextEdit, or one of their + subclasses. +*/ + +/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) + \obsolete + Sets the focus rectangle policy of \a w. The \a policy can be one of + \l{QMacStyle::FocusRectPolicy}. + + This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the + FocusDefault value does nothing anymore. If you want to set a widget back + to its default value, you must save the old value of the attribute before + you change it. + + \sa focusRectPolicy() QWidget::setAttribute() +*/ + +/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) + \obsolete + Returns the focus rectangle policy for the widget \a w. + + The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. + + In 4.3 and up this function will simply test for the + Qt::WA_MacShowFocusRect attribute and will never return + QMacStyle::FocusDefault. + + \sa setFocusRectPolicy(), QWidget::testAttribute() +*/ + +/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) + + \obsolete + + Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) + \obsolete + + Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const + \reimp +*/ + +/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const + \reimp +*/ + +/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const + \reimp +*/ + +/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const + \reimp +*/ + +/*! \fn bool QMacStyle::event(QEvent *e) + \reimp +*/ + +/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const + \internal +*/ + +/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const + + \internal +*/ + diff --git a/doc/src/classes/qpagesetupdialog.qdoc b/doc/src/classes/qpagesetupdialog.qdoc new file mode 100644 index 0000000..7f0b09e --- /dev/null +++ b/doc/src/classes/qpagesetupdialog.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPageSetupDialog + + \brief The QPageSetupDialog class provides a configuration dialog + for the page-related options on a printer. + + On Windows and Mac OS X the page setup dialog is implemented using + the native page setup dialogs. + + Note that on Windows and Mac OS X custom paper sizes won't be + reflected in the native page setup dialogs. Additionally, custom + page margins set on a QPrinter won't show in the native Mac OS X + page setup dialog. + + \sa QPrinter, QPrintDialog +*/ + + +/*! + \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) + + Constructs a page setup dialog that configures \a printer with \a + parent as the parent widget. +*/ + +/*! + \since 4.5 + + \fn QPageSetupDialog::QPageSetupDialog(QWidget *parent) + + Constructs a page setup dialog that configures a default-constructed + QPrinter with \a parent as the parent widget. + + \sa printer() +*/ + +/*! + \fn QPrinter *QPageSetupDialog::printer() + + Returns the printer that was passed to the QPageSetupDialog + constructor. +*/ + diff --git a/doc/src/classes/qpaintdevice.qdoc b/doc/src/classes/qpaintdevice.qdoc new file mode 100644 index 0000000..0f4e9a0 --- /dev/null +++ b/doc/src/classes/qpaintdevice.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPaintDevice + \brief The QPaintDevice class is the base class of objects that + can be painted. + + \ingroup multimedia + + A paint device is an abstraction of a two-dimensional space that + can be drawn using a QPainter. Its default coordinate system has + its origin located at the top-left position. X increases to the + right and Y increases downwards. The unit is one pixel. + + The drawing capabilities of QPaintDevice are currently implemented + by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and + QPrinter subclasses. + + To implement support for a new backend, you must derive from + QPaintDevice and reimplement the virtual paintEngine() function to + tell QPainter which paint engine should be used to draw on this + particular device. Note that you also must create a corresponding + paint engine to be able to draw on the device, i.e derive from + QPaintEngine and reimplement its virtual functions. + + \warning Qt requires that a QApplication object exists before + any paint devices can be created. Paint devices access window + system resources, and these resources are not initialized before + an application object is created. + + The QPaintDevice class provides several functions returning the + various device metrics: The depth() function returns its bit depth + (number of bit planes). The height() function returns its height + in default coordinate system units (e.g. pixels for QPixmap and + QWidget) while heightMM() returns the height of the device in + millimeters. Similiarily, the width() and widthMM() functions + return the width of the device in default coordinate system units + and in millimeters, respectively. Alternatively, the protected + metric() function can be used to retrieve the metric information + by specifying the desired PaintDeviceMetric as argument. + + The logicalDpiX() and logicalDpiY() functions return the + horizontal and vertical resolution of the device in dots per + inch. The physicalDpiX() and physicalDpiY() functions also return + the resolution of the device in dots per inch, but note that if + the logical and vertical resolution differ, the corresponding + QPaintEngine must handle the mapping. Finally, the numColors() + function returns the number of different colors available for the + paint device. + + \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint + System} +*/ + +/*! + \enum QPaintDevice::PaintDeviceMetric + + Describes the various metrics of a paint device. + + \value PdmWidth The width of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also width(). + + \value PdmHeight The height of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also height(). + + \value PdmWidthMM The width of the paint device in millimeters. See + also widthMM(). + + \value PdmHeightMM The height of the paint device in millimeters. See + also heightMM(). + + \value PdmNumColors The number of different colors available for + the paint device. See also numColors(). + + \value PdmDepth The bit depth (number of bit planes) of the paint + device. See also depth(). + + \value PdmDpiX The horizontal resolution of the device in dots per + inch. See also logicalDpiX(). + + \value PdmDpiY The vertical resolution of the device in dots per inch. See + also logicalDpiY(). + + \value PdmPhysicalDpiX The horizontal resolution of the device in + dots per inch. See also physicalDpiX(). + + \value PdmPhysicalDpiY The vertical resolution of the device in + dots per inch. See also physicalDpiY(). + + \sa metric() +*/ + +/*! + \fn QPaintDevice::QPaintDevice() + + Constructs a paint device. This constructor can be invoked only from + subclasses of QPaintDevice. +*/ + +/*! + \fn QPaintDevice::~QPaintDevice() + + Destroys the paint device and frees window system resources. +*/ + +/*! + \fn int QPaintDevice::devType() const + + \internal + + Returns the device type identifier, which is QInternal::Widget + if the device is a QWidget, QInternal::Pixmap if it's a + QPixmap, QInternal::Printer if it's a QPrinter, + QInternal::Picture if it's a QPicture, or + QInternal::UnknownDevice in other cases. +*/ + +/*! + \fn bool QPaintDevice::paintingActive() const + + Returns true if the device is currently being painted on, i.e. someone has + called QPainter::begin() but not yet called QPainter::end() for + this device; otherwise returns false. + + \sa QPainter::isActive() +*/ + +/*! + \fn QPaintEngine *QPaintDevice::paintEngine() const + + Returns a pointer to the paint engine used for drawing on the + device. +*/ + +/*! + \fn int QPaintDevice::metric(PaintDeviceMetric metric) const + + Returns the metric information for the given paint device \a metric. + + \sa PaintDeviceMetric +*/ + +/*! + \fn int QPaintDevice::width() const + + Returns the width of the paint device in default coordinate system + units (e.g. pixels for QPixmap and QWidget). + + \sa widthMM() +*/ + +/*! + \fn int QPaintDevice::height() const + + Returns the height of the paint device in default coordinate + system units (e.g. pixels for QPixmap and QWidget). + + \sa heightMM() +*/ + +/*! + \fn int QPaintDevice::widthMM() const + + Returns the width of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa width() +*/ + +/*! + \fn int QPaintDevice::heightMM() const + + Returns the height of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa height() +*/ + +/*! + \fn int QPaintDevice::numColors() const + + Returns the number of different colors available for the paint + device. Since this value is an int, it will not be sufficient to represent + the number of colors on 32 bit displays, in this case INT_MAX is + returned instead. +*/ + +/*! + \fn int QPaintDevice::depth() const + + Returns the bit depth (number of bit planes) of the paint device. +*/ + +/*! + \fn int QPaintDevice::logicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from widthMM(). + + Note that if the logicalDpiX() doesn't equal the physicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiY(), physicalDpiX() +*/ + +/*! + \fn int QPaintDevice::logicalDpiY() const + + Returns the vertical resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from heightMM(). + + Note that if the logicalDpiY() doesn't equal the physicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiX(), physicalDpiY() +*/ + +/*! + \fn int QPaintDevice::physicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiX() doesn't equal the logicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiY(), logicalDpiX() +*/ + +/*! + \fn int QPaintDevice::physicalDpiY() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiY() doesn't equal the logicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiX(), logicalDpiY() +*/ diff --git a/doc/src/classes/qpair.qdoc b/doc/src/classes/qpair.qdoc new file mode 100644 index 0000000..6d8a0f9 --- /dev/null +++ b/doc/src/classes/qpair.qdoc @@ -0,0 +1,229 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPair + \brief The QPair class is a template class that stores a pair of items. + + \ingroup tools + + QPair\ can be used in your application if the STL \c + pair type is not available. It stores one value of type T1 and + one value of type T2. It can be used as a return value for a + function that needs to return two values, or as the value type of + a \l{generic container}. + + Here's an example of a QPair that stores one QString and one \c + double value: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 + + The components are accessible as public data members called \l + first and \l second. For example: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 + + QPair's template data types (T1 and T2) must be \l{assignable + data types}. You cannot, for example, store a QWidget as a value; + instead, store a QWidget *. A few functions have additional + requirements; these requirements are documented on a per-function + basis. + + \sa {Generic Containers} +*/ + +/*! \typedef QPair::first_type + + The type of the first element in the pair (T1). + + \sa first +*/ + +/*! \typedef QPair::second_type + + The type of the second element in the pair (T2). + + \sa second +*/ + +/*! \variable QPair::first + + The first element in the pair. +*/ + +/*! \variable QPair::second + + The second element in the pair. +*/ + +/*! \fn QPair::QPair() + + Constructs an empty pair. The \c first and \c second elements are + initialized with \l{default-constructed values}. +*/ + +/*! + \fn QPair::QPair(const T1 &value1, const T2 &value2) + + Constructs a pair and initializes the \c first element with \a + value1 and the \c second element with \a value2. + + \sa qMakePair() +*/ + +/*! + \fn QPair &QPair::operator=(const QPair &other) + + Assigns \a other to this pair. +*/ + +/*! \fn bool operator==(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is equal to \a p2; otherwise returns false. + Two pairs compare equal if their \c first data members compare + equal and if their \c second data members compare equal. + + This function requires the T1 and T2 types to have an + implementation of \c operator==(). +*/ + +/*! \fn bool operator!=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is not equal to \a p2; otherwise returns + false. Two pairs compare as not equal if their \c first data + members are not equal or if their \c second data members are not + equal. + + This function requires the T1 and T2 types to have an + implementation of \c operator==(). +*/ + +/*! \fn bool operator<(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is less than \a p2; otherwise returns + false. The comparison is done on the \c first members of \a p1 + and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator>(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is greater than \a p2; otherwise returns + false. The comparison is done on the \c first members of \a p1 + and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator<=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is less than or equal to \a p2; otherwise + returns false. The comparison is done on the \c first members of + \a p1 and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator>=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is greater than or equal to \a p2; + otherwise returns false. The comparison is done on the \c first + members of \a p1 and \a p2; if they compare equal, the \c second + members are compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! + \fn QPair qMakePair(const T1 &value1, const T2 &value2) + + \relates QPair + + Returns a QPair\ that contains \a value1 and \a value2. + Example: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 + + This is equivalent to QPair(\a value1, \a value2), but + usually requires less typing. +*/ + +/*! \fn QDataStream &operator>>(QDataStream &in, QPair &pair) + + \relates QPair + + Reads a pair from stream \a in into \a pair. + + This function requires the T1 and T2 types to implement \c operator>>(). + + \sa {Format of the QDataStream operators} +*/ + +/*! \fn QDataStream &operator<<(QDataStream &out, const QPair &pair) + + \relates QPair + + Writes the pair \a pair to stream \a out. + + This function requires the T1 and T2 types to implement \c operator<<(). + + \sa {Format of the QDataStream operators} +*/ diff --git a/doc/src/classes/qpatternistdummy.cpp b/doc/src/classes/qpatternistdummy.cpp new file mode 100644 index 0000000..a690184 --- /dev/null +++ b/doc/src/classes/qpatternistdummy.cpp @@ -0,0 +1,1010 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* + + This file exists only to make internal all the classes you see + below. they are all in the QPatternist namespace, but they don't + have qdoc documentation because they are all declared in xxx_p.h files. Without these \internal declarations, the class names + appear on the Inheritance Hierarchy page, which is bad because + clicking on them brings up the "File not found" page. + */ + +#include "qitem_p.h" +#include "qbuiltintypes_p.h" +#include "qitem_p.h" +#include "qschematypefactory_p.h" +#include "qxmlname.h" +#include "qatomictype_p.h" + +QT_BEGIN_NAMESPACE + +using namespace QPatternist; + +/*! + \class AtomicCaster + \internal + */ + +/*! + \class AtomicComparator + \internal + */ + +/*! + \class AtomicMathematician + \internal + */ + +/*! + \class AtomicValue + \internal + */ + +/*! + \class AbstractDateTime + \internal + */ + +/*! + \class AbstractDuration + \internal + */ + +/*! + \class AbstractFloatComparator + \internal + */ + +/*! + \class AtomicString + \internal + */ + +/*! + \class Base64Binary + \internal + */ + +/*! + \class FunctionCall + \internal + */ + +/*! + \class AddingAggregate + \internal + */ + +/*! + \class AdjustTimezone + \internal + */ + +/*! + \class Aggregator + \internal + */ + +/*! + \class ComparesCaseAware + \internal + */ + +/*! + \class EncodeString + \internal + */ + +/*! + \class ExtractFromDateTimeFN + \internal + */ + +/*! + \class ExtractFromDurationFN + \internal + */ + +/*! + \class FunctionFactory + \internal + */ + +/*! + \class Numeric + \internal + */ + +/*! + \class ReportContext + \internal + */ + +/*! + \class AbstractFunctionFactory + \internal + */ + +/*! + \class DynamicContext + \internal + */ + +/*! + \class IdFN + \internal + */ + +/*! + \class IntegerType + \internal + */ + +/*! + \class NamespaceResolver + \internal + */ + +/*! + \class PatternPlatform + \internal + */ + +/*! \class DocumentProjector + \internal */ +/*! \class NodeBuilder + \internal */ +/*! \class AccelTreeBuilder + \internal */ +/*! \class OutputValidator + \internal */ +/*! \class NetworkLoop + \internal */ +/*! \class QIODeviceDelegate + \internal */ +/*! \class URILoader + \internal */ +/*! \class AbsFN + \internal */ +/*! \class AbstractDateTimeComparator + \internal */ +/*! \class AbstractDateTimeMathematician + \internal */ +/*! \class AbstractDateTimeToDateCaster + \internal */ +/*! \class AbstractDateTimeToDateTimeCaster + \internal */ +/*! \class AbstractDateTimeToGDayCaster + \internal */ +/*! \class AbstractDateTimeToGMonthCaster + \internal */ +/*! \class AbstractDateTimeToGMonthDayCaster + \internal */ +/*! \class AbstractDateTimeToGYearCaster + \internal */ +/*! \class AbstractDateTimeToGYearMonthCaster + \internal */ +/*! \class AbstractDateTimeToTimeCaster + \internal */ +/*! \class AbstractDurationComparator + \internal */ +/*! \class AbstractDurationToDayTimeDurationCaster + \internal */ +/*! \class AbstractDurationToDurationCaster + \internal */ +/*! \class AbstractDurationToYearMonthDurationCaster + \internal */ +/*! \class AbstractFloat + \internal */ +/*! \class AbstractFloatMathematician + \internal */ +/*! \class AbstractFloatSortComparator + \internal */ +/*! \class ConstructorFunctionsFactory + \internal */ +/*! \class XPath10CoreFunctions + \internal */ +/*! \class XPath20CoreFunctions + \internal */ +/*! \class AdjustDateTimeToTimezoneFN + \internal */ +/*! \class AdjustDateToTimezoneFN + \internal */ +/*! \class AdjustTimeToTimezoneFN + \internal */ +/*! \class AnyToDerivedStringCaster + \internal */ +/*! \class AnyURI + \internal */ +/*! \class Atomizer + \internal */ +/*! \class AvgFN + \internal */ +/*! \class Base64BinaryComparatorLocator + \internal */ +/*! \class Base64BinaryToHexBinaryCaster + \internal */ +/*! \class Base64BinaryType + \internal */ +/*! \class BaseURIFN + \internal */ +/*! \class BinaryDataComparator + \internal */ +/*! \class Boolean + \internal */ +/*! \class BooleanComparator + \internal */ +/*! \class BooleanComparatorLocator + \internal */ +/*! \class BooleanFN + \internal */ +/*! \class BooleanToAbstractFloatCaster + \internal */ +/*! \class BooleanToDecimalCaster + \internal */ +/*! \class BooleanToDerivedIntegerCaster + \internal */ +/*! \class BooleanToIntegerCaster + \internal */ +/*! \class BooleanType + \internal */ +/*! \class BuiltinNodeType + \internal */ +/*! \class CardinalityVerifier + \internal */ +/*! \class CaseInsensitiveStringComparator + \internal */ +/*! \class CeilingFN + \internal */ +/*! \class CodepointEqualFN + \internal */ +/*! \class CodepointsToStringFN + \internal */ +/*! \class CollectionFN + \internal */ +/*! \class CompareFN + \internal */ +/*! \class ComparingAggregator + \internal */ +/*! \class ConcatFN + \internal */ +/*! \class ContainsFN + \internal */ +/*! \class CountFN + \internal */ +/*! \class CurrentDateFN + \internal */ +/*! \class CurrentDateTimeFN + \internal */ +/*! \class CurrentTimeFN + \internal */ +/*! \class Date + \internal */ +/*! \class DateComparatorLocator + \internal */ +/*! \class DateMathematicianLocator + \internal */ +/*! \class DateTime + \internal */ +/*! \class DateTimeComparatorLocator + \internal */ +/*! \class DateTimeDurationMathematician + \internal */ +/*! \class DateTimeFN + \internal */ +/*! \class DateTimeMathematicianLocator + \internal */ +/*! \class DateTimeType + \internal */ +/*! \class DateType + \internal */ +/*! \class DayFromAbstractDateTimeFN + \internal */ +/*! \class DayTimeDuration + \internal */ +/*! \class DayTimeDurationComparatorLocator + \internal */ +/*! \class DayTimeDurationMathematicianLocator + \internal */ +/*! \class DayTimeDurationType + \internal */ +/*! \class DaysFromDurationFN + \internal */ +/*! \class Decimal + \internal */ +/*! \class DecimalComparator + \internal */ +/*! \class DecimalComparatorLocator + \internal */ +/*! \class DecimalMathematician + \internal */ +/*! \class DecimalMathematicianLocator + \internal */ +/*! \class DecimalType + \internal */ +/*! \class DeduplicateIterator + \internal */ +/*! \class DeepEqualFN + \internal */ +/*! \class DefaultCollationFN + \internal */ +/*! \class DerivedInteger + \internal */ +/*! \class DerivedString + \internal */ +/*! \class DistinctValuesFN + \internal */ +/*! \class DocAvailableFN + \internal */ +/*! \class DocFN + \internal */ +/*! \class DocumentURIFN + \internal */ +/*! \class DoubleComparatorLocator + \internal */ +/*! \class DoubleMathematicianLocator + \internal */ +/*! \class DoubleType + \internal */ +/*! \class Duration + \internal */ +/*! \class DurationComparatorLocator + \internal */ +/*! \class DurationDurationDivisor + \internal */ +/*! \class DurationDurationMathematician + \internal */ +/*! \class DurationNumericMathematician + \internal */ +/*! \class DurationType + \internal */ +/*! \class DelegatingDynamicContext + \internal */ +/*! \class Focus + \internal */ +/*! \class ReceiverDynamicContext + \internal */ +/*! \class EmptyIterator + \internal */ +/*! \class EncodeForURIFN + \internal */ +/*! \class EndsWithFN + \internal */ +/*! \class ErrorFN + \internal */ +/*! \class EscapeHtmlURIFN + \internal */ +/*! \class EvaluationCache + \internal */ +/*! \class Existence + \internal */ +/*! \class ExpressionVisitor + \internal */ +/*! \class ExpressionVisitorResult + \internal */ +/*! \class FalseFN + \internal */ +/*! \class FloatComparatorLocator + \internal */ +/*! \class FloatMathematicianLocator + \internal */ +/*! \class FloatType + \internal */ +/*! \class FloorFN + \internal */ +/*! \class FunctionArgument + \internal */ +/*! \class FunctionAvailableFN + \internal */ +/*! \class FunctionFactoryCollection + \internal */ +/*! \class FunctionSignature + \internal */ +/*! \class GDay + \internal */ +/*! \class GDayComparatorLocator + \internal */ +/*! \class GDayType + \internal */ +/*! \class GMonth + \internal */ +/*! \class GMonthComparatorLocator + \internal */ +/*! \class GMonthDay + \internal */ +/*! \class GMonthDayComparatorLocator + \internal */ +/*! \class GMonthDayType + \internal */ +/*! \class GMonthType + \internal */ +/*! \class GYear + \internal */ +/*! \class GYearComparatorLocator + \internal */ +/*! \class GYearMonth + \internal */ +/*! \class GYearMonthComparatorLocator + \internal */ +/*! \class GYearMonthType + \internal */ +/*! \class GYearType + \internal */ +/*! \class HexBinary + \internal */ +/*! \class HexBinaryComparatorLocator + \internal */ +/*! \class HexBinaryToBase64BinaryCaster + \internal */ +/*! \class HexBinaryType + \internal */ +/*! \class HoursFromAbstractDateTimeFN + \internal */ +/*! \class HoursFromDurationFN + \internal */ +/*! \class IdrefFN + \internal */ +/*! \class ImplicitTimezoneFN + \internal */ +/*! \class InScopePrefixesFN + \internal */ +/*! \class IndexOfFN + \internal */ +/*! \class InsertBeforeFN + \internal */ +/*! \class Integer + \internal */ +/*! \class IntegerComparator + \internal */ +/*! \class IntegerComparatorLocator + \internal */ +/*! \class IntegerMathematician + \internal */ +/*! \class IntegerMathematicianLocator + \internal */ +/*! \class DerivedIntegerType + \internal */ +/*! \class IriToURIFN + \internal */ +/*! \class ItemMappingIterator + \internal */ +/*! \class ItemVerifier + \internal */ +/*! \class LangFN + \internal */ +/*! \class LastFN + \internal */ +/*! \class LocalNameFN + \internal */ +/*! \class LocalNameFromQNameFN + \internal */ +/*! \class LowerCaseFN + \internal */ +/*! \class MinutesFromAbstractDateTimeFN + \internal */ +/*! \class MinutesFromDurationFN + \internal */ +/*! \class MonthFromAbstractDateTimeFN + \internal */ +/*! \class MonthsFromDurationFN + \internal */ +/*! \class NOTATIONType + \internal */ +/*! \class NameFN + \internal */ +/*! \class NamePool + \internal */ +/*! \class DelegatingNamespaceResolver + \internal */ +/*! \class GenericNamespaceResolver + \internal */ +/*! \class NodeNamespaceResolver + \internal */ +/*! \class NamespaceURIFN + \internal */ +/*! \class NamespaceURIForPrefixFN + \internal */ +/*! \class NamespaceURIFromQNameFN + \internal */ +/*! \class NilledFN + \internal */ +/*! \class NodeNameFN + \internal */ +/*! \class NormalizeSpaceFN + \internal */ +/*! \class NormalizeUnicodeFN + \internal */ +/*! \class NotFN + \internal */ +/*! \class NumberFN + \internal */ +/*! \class NumericToAbstractFloatCaster + \internal */ +/*! \class NumericToBooleanCaster + \internal */ +/*! \class NumericToDecimalCaster + \internal */ +/*! \class NumericToDerivedIntegerCaster + \internal */ +/*! \class OperandSwitcherMathematician + \internal */ +/*! \class ParserContext + \internal */ +/*! \class MatchesFN + \internal */ +/*! \class ReplaceFN + \internal */ +/*! \class TokenizeFN + \internal */ +/*! \class PositionFN + \internal */ +/*! \class PrefixFromQNameFN + \internal */ +/*! \class AccelTree + \internal */ +/*! \class QNameComparator + \internal */ +/*! \class QNameComparatorLocator + \internal */ +/*! \class QNameFN + \internal */ +/*! \class QNameType + \internal */ +/*! \class QNameValue + \internal */ +/*! \class RemoveFN + \internal */ +/*! \class ResolveQNameFN + \internal */ +/*! \class ResolveURIFN + \internal */ +/*! \class ResourceLoader + \internal */ +/*! \class AccelTreeResourceLoader + \internal */ +/*! \class ReverseFN + \internal */ +/*! \class RootFN + \internal */ +/*! \class RoundFN + \internal */ +/*! \class RoundHalfToEvenFN + \internal */ +/*! \class SchemaTime + \internal */ +/*! \class SchemaTimeComparatorLocator + \internal */ +/*! \class SchemaTimeMathematicianLocator + \internal */ +/*! \class SchemaTimeType + \internal */ +/*! \class SecondsFromAbstractDateTimeFN + \internal */ +/*! \class SecondsFromDurationFN + \internal */ +/*! \class SelfToSelfCaster + \internal */ +/*! \class SequenceMappingIterator + \internal */ +/*! \class SingletonIterator + \internal */ +/*! \class SortTuple + \internal */ +/*! \class StartsWithFN + \internal */ +/*! \class StaticBaseURIFN + \internal */ +/*! \class StaticContext + \internal */ +/*! \class DelegatingStaticContext + \internal */ +/*! \class StaticFocusContext + \internal */ +/*! \class StaticNamespaceContext + \internal */ +/*! \class GenericStaticContext + \internal */ +/*! \class StringComparator + \internal */ +/*! \class StringComparatorLocator + \internal */ +/*! \class StringFN + \internal */ +/*! \class StringJoinFN + \internal */ +/*! \class StringLengthFN + \internal */ +/*! \class StringToAbstractFloatCaster + \internal */ +/*! \class StringToBase64BinaryCaster + \internal */ +/*! \class StringToBooleanCaster + \internal */ +/*! \class StringToCodepointsFN + \internal */ +/*! \class StringToDateCaster + \internal */ +/*! \class StringToDateTimeCaster + \internal */ +/*! \class StringToDayTimeDurationCaster + \internal */ +/*! \class StringToDecimalCaster + \internal */ +/*! \class StringToDerivedIntegerCaster + \internal */ +/*! \class StringToDurationCaster + \internal */ +/*! \class StringToGDayCaster + \internal */ +/*! \class StringToGMonthCaster + \internal */ +/*! \class StringToGMonthDayCaster + \internal */ +/*! \class StringToGYearCaster + \internal */ +/*! \class StringToGYearMonthCaster + \internal */ +/*! \class StringToHexBinaryCaster + \internal */ +/*! \class StringToIntegerCaster + \internal */ +/*! \class StringToTimeCaster + \internal */ +/*! \class StringToYearMonthDurationCaster + \internal */ +/*! \class StringType + \internal */ +/*! \class DerivedStringType + \internal */ +/*! \class SubsequenceFN + \internal */ +/*! \class SubstringAfterFN + \internal */ +/*! \class SubstringBeforeFN + \internal */ +/*! \class SubstringFN + \internal */ +/*! \class SumFN + \internal */ +/*! \class SystemPropertyFN + \internal */ +/*! \class TimezoneFromAbstractDateTimeFN + \internal */ +/*! \class ToAnyURICaster + \internal */ +/*! \class ToAnyURICasterLocator + \internal */ +/*! \class ToBase64BinaryCasterLocator + \internal */ +/*! \class ToBooleanCasterLocator + \internal */ +/*! \class ToDateCasterLocator + \internal */ +/*! \class ToDateTimeCasterLocator + \internal */ +/*! \class ToDayTimeDurationCasterLocator + \internal */ +/*! \class ToDecimalCasterLocator + \internal */ +/*! \class ToDoubleCasterLocator + \internal */ +/*! \class ToDurationCasterLocator + \internal */ +/*! \class ToFloatCasterLocator + \internal */ +/*! \class ToGDayCasterLocator + \internal */ +/*! \class ToGMonthCasterLocator + \internal */ +/*! \class ToGMonthDayCasterLocator + \internal */ +/*! \class ToGYearCasterLocator + \internal */ +/*! \class ToGYearMonthCasterLocator + \internal */ +/*! \class ToHexBinaryCasterLocator + \internal */ +/*! \class ToIntegerCasterLocator + \internal */ +/*! \class ToDerivedIntegerCasterLocator + \internal */ +/*! \class ToQNameCasterLocator + \internal */ +/*! \class ToSchemaTimeCasterLocator + \internal */ +/*! \class ToStringCaster + \internal */ +/*! \class ToStringCasterLocator + \internal */ +/*! \class ToDerivedStringCasterLocator + \internal */ +/*! \class ToUntypedAtomicCaster + \internal */ +/*! \class ToUntypedAtomicCasterLocator + \internal */ +/*! \class ToYearMonthDurationCasterLocator + \internal */ +/*! \class Tokenizer + \internal */ +/*! \class XQueryTokenizer + \internal */ +/*! \class TraceFN + \internal */ +/*! \class TranslateFN + \internal */ +/*! \class TrueFN + \internal */ +/*! \class UntypedAtomic + \internal */ +/*! \class UntypedAtomicConverter + \internal */ +/*! \class ArgumentConverter + \internal */ +/*! \class UntypedAtomicType + \internal */ +/*! \class UpperCaseFN + \internal */ +/*! \class ValidationError + \internal */ +/*! \class VariableDeclaration + \internal */ +/*! \class VariableLoader + \internal */ +/*! \class YearFromAbstractDateTimeFN + \internal */ +/*! \class YearMonthDuration + \internal */ +/*! \class YearMonthDurationComparatorLocator + \internal */ +/*! \class YearMonthDurationMathematicianLocator + \internal */ +/*! \class YearMonthDurationType + \internal */ +/*! \class YearsFromDurationFN + \internal + */ +/*! \class DocumentContentValidator + \internal */ +/*! \class AtomicTypeVisitor + \internal */ +/*! \class AtomicCasterLocator + \internal */ +/*! \class AtomicTypeVisitorResult + \internal */ +/*! \class Expression + \internal */ +/*! \class EmptyContainer + \internal */ +/*! \class AxisStep + \internal */ +/*! \class ContextItem + \internal */ +/*! \class EmptySequence + \internal */ +/*! \class ExternalVariableReference + \internal */ +/*! \class Literal + \internal */ +/*! \class LiteralSequence + \internal */ +/*! \class NamespaceConstructor + \internal */ +/*! \class ParentNodeAxis + \internal */ +/*! \class VariableReference + \internal */ +/*! \class ArgumentReference + \internal */ +/*! \class ExpressionVariableReference + \internal */ +/*! \class PositionalVariableReference + \internal */ +/*! \class RangeVariableReference + \internal */ +/*! \class PairContainer + \internal */ +/*! \class AndExpression + \internal */ +/*! \class OrExpression + \internal */ +/*! \class ArithmeticExpression + \internal */ +/*! \class UnaryExpression + \internal */ +/*! \class AttributeConstructor + \internal */ +/*! \class CombineNodes + \internal */ +/*! \class ElementConstructor + \internal */ +/*! \class ForClause + \internal */ +/*! \class GeneralComparison + \internal */ +/*! \class GenericPredicate + \internal */ +/*! \class TruthPredicate + \internal */ +/*! \class LetClause + \internal */ +/*! \class NodeComparison + \internal */ +/*! \class Path + \internal */ +/*! \class ProcessingInstructionConstructor + \internal */ +/*! \class QuantifiedExpression + \internal */ +/*! \class RangeExpression + \internal */ +/*! \class ValueComparison + \internal */ +/*! \class SingleContainer + \internal */ +/*! \class AttributeNameValidator + \internal */ +/*! \class CastAs + \internal */ +/*! \class CastableAs + \internal */ +/*! \class CollationChecker + \internal */ +/*! \class CommentConstructor + \internal */ +/*! \class CopyOf + \internal */ +/*! \class DocumentConstructor + \internal */ +/*! \class DynamicContextStore + \internal */ +/*! \class FirstItemPredicate + \internal */ +/*! \class InstanceOf + \internal */ +/*! \class NCNameConstructor + \internal */ +/*! \class NodeSortExpression + \internal */ +/*! \class OrderBy + \internal */ +/*! \class QNameConstructor + \internal */ +/*! \class SimpleContentConstructor + \internal */ +/*! \class TextNodeConstructor + \internal */ +/*! \class TreatAs + \internal */ +/*! \class TripleContainer + \internal */ +/*! \class IfThenClause + \internal */ +/*! \class UnlimitedContainer + \internal */ +/*! \class ExpressionSequence + \internal */ +/*! \class ReturnOrderBy + \internal */ +/*! \class UserFunctionCallsite + \internal */ +/*! \class ExpressionCreator + \internal */ +/*! \class ByIDCreator + \internal */ +/*! \class ExpressionFactory + \internal */ +/*! \class ExpressionIdentifier + \internal */ +/*! \class BooleanIdentifier + \internal */ +/*! \class ByIDIdentifier + \internal */ +/*! \class BySequenceTypeIdentifier + \internal */ +/*! \class ComparisonIdentifier + \internal */ +/*! \class IntegerIdentifier + \internal */ +/*! \class ExternalVariableLoader + \internal */ +/*! \class ItemType + \internal */ +/*! \class AnyItemType + \internal */ +/*! \class AnyNodeType + \internal */ +/*! \class AbstractNodeTest + \internal */ +/*! \class LocalNameTest + \internal */ +/*! \class NamespaceNameTest + \internal */ +/*! \class QNameTest + \internal */ +/*! \class AtomicType + \internal */ +/*! \class BuiltinAtomicType + \internal */ +/*! \class AnyAtomicType + \internal */ +/*! \class AnyURIType + \internal */ +/*! \class NumericType + \internal */ +/*! \class EBVType + \internal */ +/*! \class EmptySequenceType + \internal */ +/*! \class MultiItemType + \internal */ +/*! \class NoneType + \internal */ +/*! \class OptimizationPass + \internal */ +/*! \class ParameterizedAtomicTypeVisitor + \internal */ +/*! \class AtomicComparatorLocator + \internal */ +/*! \class AtomicMathematicianLocator + \internal */ +/*! \class SchemaComponent + \internal */ +/*! \class SchemaType + \internal */ +/*! \class AnyType + \internal */ +/*! \class AnySimpleType + \internal */ +/*! \class Untyped + \internal */ +/*! \class SchemaTypeFactory + \internal */ +/*! \class BasicTypesFactory + \internal */ +/*! \class SequenceType + \internal */ +/*! \class GenericSequenceType + \internal */ +/*! \class UserFunction + \internal +*/ +QT_END_NAMESPACE diff --git a/doc/src/classes/qplugin.qdoc b/doc/src/classes/qplugin.qdoc new file mode 100644 index 0000000..4fbd198 --- /dev/null +++ b/doc/src/classes/qplugin.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Macros for Defining Plugins + + \brief The header files defines macros for defining plugins. + + \sa {How to Create Qt Plugins} +*/ + +/*! + \macro Q_DECLARE_INTERFACE(ClassName, Identifier) + \relates + + This macro associates the given \a Identifier (a string literal) + to the interface class called \a ClassName. The \a Identifier must + be unique. For example: + + \snippet examples/tools/plugandpaint/interfaces.h 3 + + This macro is normally used right after the class definition for + \a ClassName, in a header file. See the + \l{tools/plugandpaint}{Plug & Paint} example for details. + + If you want to use Q_DECLARE_INTERFACE with interface classes + declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE + is not inside a namespace though. For example: + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 + + \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} +*/ + +/*! + \macro Q_EXPORT_PLUGIN(ClassName) + \relates + \obsolete + + Use Q_EXPORT_PLUGIN2() instead. This macro is equivalent to + Q_EXPORT_PLUGIN2(\a ClassName, \a ClassName). +*/ + +/*! + \macro Q_EXPORT_PLUGIN2(PluginName, ClassName) + \relates + \since 4.1 + \keyword Q_EXPORT_PLUGIN2 + + This macro exports the plugin class \a ClassName for the plugin specified + by \a PluginName. The value of \a PluginName should correspond to the + \l{qmake Variable Reference#TARGET}{TARGET} specified in the plugin's + project file. + + There should be exactly one occurrence of this macro in the source code + for a Qt plugin, and it should be used where the implementation is written + rather than in a header file. + + Example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 + + See the \l{tools/plugandpaint}{Plug & Paint} example for details. + + \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins} +*/ + +/*! + \macro Q_IMPORT_PLUGIN(PluginName) + \relates + + This macro imports the plugin named \a PluginName, corresponding + to the \l{qmake Variable Reference#TARGET}{TARGET} specified in the + plugin's project file. + + Inserting this macro into your application's source code will allow + you to make use of a static plugin. + + Example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 + + Static plugins must also be included by the linker when your + application is built. For Qt's predefined plugins, + you can use the \c QTPLUGIN to add + the required plugins to your build. For example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 + + \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} +*/ + +/*! + \macro Q_EXPORT_STATIC_PLUGIN(ClassName) + \relates + \internal +*/ diff --git a/doc/src/classes/qprintdialog.qdoc b/doc/src/classes/qprintdialog.qdoc new file mode 100644 index 0000000..8011f62 --- /dev/null +++ b/doc/src/classes/qprintdialog.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifdef QT3_SUPPORT +/*! + \fn QPrinter *QPrintDialog::printer() const + + Returns a pointer to the printer this dialog configures, or 0 if + this dialog does not operate on any printer. + + This function is available for Unix platforms only. +*/ + +/*! + \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) + + Sets this dialog to configure printer \a printer, or no printer if \a printer + is null. If \a pickupSettings is true, the dialog reads most of + its settings from \a printer. If \a pickupSettings is false (the + default) the dialog keeps its old settings. + + This function is available for Unix platforms only. +*/ + +/*! + \fn void QPrintDialog::addButton(QPushButton *button) + + Adds the \a button to the layout of the print dialog. The added + buttons are arranged from the left to the right below the + last groupbox of the printdialog. + + This function is available for Unix platforms only. +*/ +#endif diff --git a/doc/src/classes/qprinterinfo.qdoc b/doc/src/classes/qprinterinfo.qdoc new file mode 100644 index 0000000..a4ffeb2 --- /dev/null +++ b/doc/src/classes/qprinterinfo.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPrinterInfo + + \brief The QPrinterInfo class gives access to information about + existing printers. + + Use the static functions to generate a list of QPrinterInfo + objects. Each QPrinterInfo object in the list represents a single + printer and can be queried for name, supported paper sizes, and + whether or not it is the default printer. + + \since 4.4 +*/ + +/*! + \fn QList QPrinterInfo::availablePrinters() + + Returns a list of available printers on the system. +*/ + +/*! + \fn QPrinterInfo QPrinterInfo::defaultPrinter() + + Returns the default printer on the system. + + The return value should be checked using isNull() before being + used, in case there is no default printer. + + \sa isNull() +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo() + + Constructs an empty QPrinterInfo object. + + \sa isNull() +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo(const QPrinterInfo& src) + + Constructs a copy of \a src. +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo(const QPrinter& printer) + + Constructs a QPrinterInfo object from \a printer. +*/ + +/*! + \fn QPrinterInfo::~QPrinterInfo() + + Destroys the QPrinterInfo object. References to the values in the + object become invalid. +*/ + +/*! + \fn QPrinterInfo& QPrinterInfo::operator=(const QPrinterInfo& src) + + Sets the QPrinterInfo object to be equal to \a src. +*/ + +/*! + \fn QString QPrinterInfo::printerName() const + + Returns the name of the printer. + + \sa QPrinter::setPrinterName() +*/ + +/*! + \fn bool QPrinterInfo::isNull() const + + Returns whether this QPrinterInfo object holds a printer definition. + + An empty QPrinterInfo object could result for example from calling + defaultPrinter() when there are no printers on the system. +*/ + +/*! + \fn bool QPrinterInfo::isDefault() const + + Returns whether this printer is the default printer. +*/ + +/*! + \fn QList< QPrinter::PaperSize> QPrinterInfo::supportedPaperSizes() const + \since 4.4 + + Returns a list of supported paper sizes by the printer. + + Not all printer drivers support this query, so the list may be empty. + On Mac OS X 10.3, this function always returns an empty list. +*/ diff --git a/doc/src/classes/qset.qdoc b/doc/src/classes/qset.qdoc new file mode 100644 index 0000000..0db3775 --- /dev/null +++ b/doc/src/classes/qset.qdoc @@ -0,0 +1,953 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSet + \brief The QSet class is a template class that provides a hash-table-based set. + + \ingroup tools + \ingroup shared + \reentrant + \mainclass + + QSet is one of Qt's generic \l{container classes}. It stores + values in an unspecified order and provides very fast lookup of + the values. Internally, QSet is implemented as a QHash. + + Here's an example QSet with QString values: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 + + To insert a value into the set, use insert(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 + + Another way to insert items into the set is to use operator<<(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 + + To test whether an item belongs to the set or not, use contains(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 + + If you want to navigate through all the values stored in a QSet, + you can use an iterator. QSet supports both \l{Java-style + iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style + iterators} (QSet::iterator and QSet::const_iterator). Here's how + to iterate over a QSet using a Java-style iterator: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 + + Here's the same code, but using an STL-style iterator: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 + + QSet is unordered, so an iterator's sequence cannot be assumed to + be predictable. If ordering by key is required, use a QMap. + + To navigate through a QSet, you can also use \l{foreach}: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 + + Items can be removed from the set using remove(). There is also a + clear() function that removes all items. + + QSet's value data type must be an \l{assignable data type}. You + cannot, for example, store a QWidget as a value; instead, store a + QWidget *. In addition, the type must provide \c operator==(), and + there must also be a global qHash() function that returns a hash + value for an argument of the key's type. See the QHash + documentation for a list of types supported by qHash(). + + Internally, QSet uses a hash table to perform lookups. The hash + table automatically grows and shrinks to provide fast lookups + without wasting memory. You can still control the size of the hash + table by calling reserve(), if you already know approximately how + many elements the QSet will contain, but this isn't necessary to + obtain good performance. You can also call capacity() to retrieve + the hash table's size. + + \sa QSetIterator, QMutableSetIterator, QHash, QMap +*/ + +/*! + \fn QSet::QSet() + + Constructs an empty set. + + \sa clear() +*/ + +/*! + \fn QSet::QSet(const QSet &other) + + Constructs a copy of \a other. + + This operation occurs in \l{constant time}, because QSet is + \l{implicitly shared}. This makes returning a QSet from a + function very fast. If a shared instance is modified, it will be + copied (copy-on-write), and this takes \l{linear time}. + + \sa operator=() +*/ + +/*! + \fn QSet &QSet::operator=(const QSet &other) + + Assigns the \a other set to this set and returns a reference to + this set. +*/ + +/*! + \fn bool QSet::operator==(const QSet &other) const + + Returns true if the \a other set is equal to this set; otherwise + returns false. + + Two sets are considered equal if they contain the same elements. + + This function requires the value type to implement \c operator==(). + + \sa operator!=() +*/ + +/*! + \fn bool QSet::operator!=(const QSet &other) const + + Returns true if the \a other set is not equal to this set; otherwise + returns false. + + Two sets are considered equal if they contain the same elements. + + This function requires the value type to implement \c operator==(). + + \sa operator==() +*/ + +/*! + \fn int QSet::size() const + + Returns the number of items in the set. + + \sa isEmpty(), count() +*/ + +/*! + \fn bool QSet::isEmpty() const + + Returns true if the set contains no elements; otherwise returns + false. + + \sa size() +*/ + +/*! + \fn int QSet::capacity() const + + Returns the number of buckets in the set's internal hash + table. + + The sole purpose of this function is to provide a means of fine + tuning QSet's memory usage. In general, you will rarely ever need + to call this function. If you want to know how many items are in + the set, call size(). + + \sa reserve(), squeeze() +*/ + +/*! \fn void QSet::reserve(int size) + + Ensures that the set's internal hash table consists of at + least \a size buckets. + + This function is useful for code that needs to build a huge set + and wants to avoid repeated reallocation. For example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 + + Ideally, \a size should be slightly more than the maximum number + of elements expected in the set. \a size doesn't have to be prime, + because QSet will use a prime number internally anyway. If \a size + is an underestimate, the worst that will happen is that the QSet + will be a bit slower. + + In general, you will rarely ever need to call this function. + QSet's internal hash table automatically shrinks or grows to + provide good performance without wasting too much memory. + + \sa squeeze(), capacity() +*/ + +/*! + \fn void QSet::squeeze() + + Reduces the size of the set's internal hash table to save + memory. + + The sole purpose of this function is to provide a means of fine + tuning QSet's memory usage. In general, you will rarely ever + need to call this function. + + \sa reserve(), capacity() +*/ + +/*! + \fn void QSet::detach() + + \internal + + Detaches this set from any other sets with which it may share + data. + + \sa isDetached() +*/ + +/*! \fn bool QSet::isDetached() const + + \internal + + Returns true if the set's internal data isn't shared with any + other set object; otherwise returns false. + + \sa detach() +*/ + +/*! + \fn void QSet::setSharable(bool sharable) + \internal +*/ + +/*! + \fn void QSet::clear() + + Removes all elements from the set. + + \sa remove() +*/ + +/*! + \fn bool QSet::remove(const T &value) + + Removes any occurrence of item \a value from the set. Returns + true if an item was actually removed; otherwise returns false. + + \sa contains(), insert() +*/ + +/*! + \fn QSet::iterator QSet::erase(iterator pos) + \since 4.2 + + Removes the item at the iterator position \a pos from the set, and + returns an iterator positioned at the next item in the set. + + Unlike remove(), this function never causes QSet to rehash its + internal data structure. This means that it can safely be called + while iterating, and won't affect the order of items in the set. + + \sa remove(), find() +*/ + +/*! \fn QSet::const_iterator QSet::find(const T &value) const + \since 4.2 + + Returns a const iterator positioned at the item \a value in the + set. If the set contains no item \a value, the function returns + constEnd(). + + \sa constFind(), contains() +*/ + +/*! \fn QSet::iterator QSet::find(const T &value) + \since 4.2 + \overload + + Returns a non-const iterator positioned at the item \a value in + the set. If the set contains no item \a value, the function + returns end(). +*/ + +/*! \fn QSet::const_iterator QSet::constFind(const T &value) const + \since 4.2 + + Returns a const iterator positioned at the item \a value in the + set. If the set contains no item \a value, the function returns + constEnd(). + + \sa find(), contains() +*/ + +/*! + \fn bool QSet::contains(const T &value) const + + Returns true if the set contains item \a value; otherwise returns + false. + + \sa insert(), remove(), find() +*/ + +/*! + \fn bool QSet::contains(const QSet &other) const + \since 4.6 + + Returns true if the set contains all items from the \a other set; + otherwise returns false. + + \sa insert(), remove(), find() +*/ + +/*! \fn QSet::const_iterator QSet::begin() const + + Returns a const \l{STL-style iterator} positioned at the first + item in the set. + + \sa constBegin(), end() +*/ + +/*! \fn QSet::iterator QSet::begin() + \since 4.2 + \overload + + Returns a non-const \l{STL-style iterator} positioned at the first + item in the set. +*/ + +/*! \fn QSet::const_iterator QSet::constBegin() const + + Returns a const \l{STL-style iterator} positioned at the first + item in the set. + + \sa begin(), constEnd() +*/ + +/*! \fn QSet::const_iterator QSet::end() const + + Returns a const \l{STL-style iterator} positioned at the imaginary + item after the last item in the set. + + \sa constEnd(), begin() +*/ + +/*! \fn QSet::iterator QSet::end() + \since 4.2 + \overload + + Returns a non-const \l{STL-style iterator} pointing to the + imaginary item after the last item in the set. +*/ + +/*! \fn QSet::const_iterator QSet::constEnd() const + + Returns a const \l{STL-style iterator} pointing to the imaginary + item after the last item in the set. + + \sa constBegin(), end() +*/ + +/*! + \typedef QSet::Iterator + \since 4.2 + + Qt-style synonym for QSet::iterator. +*/ + +/*! + \typedef QSet::ConstIterator + + Qt-style synonym for QSet::const_iterator. +*/ + +/*! + \typedef QSet::const_pointer + + Typedef for const T *. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::const_reference + + Typedef for const T &. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::difference_type + + Typedef for const ptrdiff_t. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::key_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::pointer + + Typedef for T *. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::size_type + + Typedef for int. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::value_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! + \fn QSet::const_iterator QSet::insert(const T &value) + + Inserts item \a value into the set, if \a value isn't already + in the set, and returns an iterator pointing at the inserted + item. + + \sa operator<<(), remove(), contains() +*/ + +/*! + \fn QSet &QSet::unite(const QSet &other) + + Each item in the \a other set that isn't already in this set is + inserted into this set. A reference to this set is returned. + + \sa operator|=(), intersect(), subtract() +*/ + +/*! + \fn QSet &QSet::intersect(const QSet &other) + + Removes all items from this set that are not contained in the + \a other set. A reference to this set is returned. + + \sa operator&=(), unite(), subtract() +*/ + +/*! + \fn QSet &QSet::subtract(const QSet &other) + + Removes all items from this set that are contained in the + \a other set. Returns a reference to this set. + + \sa operator-=(), unite(), intersect() +*/ + +/*! + \fn bool QSet::empty() const + + Returns true if the set is empty. This function is provided + for STL compatibility. It is equivalent to isEmpty(). +*/ + +/*! + \fn bool QSet::count() const + + Same as size(). +*/ + +/*! + \fn QSet &QSet::operator<<(const T &value) + \fn QSet &QSet::operator+=(const T &value) + \fn QSet &QSet::operator|=(const T &value) + + Inserts a new item \a value and returns a reference to the set. + If \a value already exists in the set, the set is left unchanged. + + \sa insert() +*/ + +/*! + \fn QSet &QSet::operator-=(const T &value) + + Removes the occurrence of item \a value from the set, if + it is found, and returns a reference to the set. If the + \a value is not contained the set, nothing is removed. + + \sa remove() +*/ + +/*! + \fn QSet &QSet::operator|=(const QSet &other) + \fn QSet &QSet::operator+=(const QSet &other) + + Same as unite(\a other). + + \sa operator|(), operator&=(), operator-=() +*/ + +/*! + \fn QSet &QSet::operator&=(const QSet &other) + + Same as intersect(\a other). + + \sa operator&(), operator|=(), operator-=() +*/ + +/*! + \fn QSet &QSet::operator&=(const T &value) + + \overload + + Same as intersect(\e{other}), if we consider \e{other} to be a set + that contains the singleton \a value. +*/ + + +/*! + \fn QSet &QSet::operator-=(const QSet &other) + + Same as subtract(\a{other}). + + \sa operator-(), operator|=(), operator&=() +*/ + +/*! + \fn QSet QSet::operator|(const QSet &other) const + \fn QSet QSet::operator+(const QSet &other) const + + Returns a new QSet that is the union of this set and the + \a other set. + + \sa unite(), operator|=(), operator&(), operator-() +*/ + +/*! + \fn QSet QSet::operator&(const QSet &other) const + + Returns a new QSet that is the intersection of this set and the + \a other set. + + \sa intersect(), operator&=(), operator|(), operator-() +*/ + +/*! + \fn QSet QSet::operator-(const QSet &other) const + + Returns a new QSet that is the set difference of this set and + the \a other set, i.e., this set - \a other set. + + \sa subtract(), operator-=(), operator|(), operator&() +*/ + +/*! + \fn QSet QSet::operator-(const QSet &other) + \fn QSet QSet::operator|(const QSet &other) + \fn QSet QSet::operator+(const QSet &other) + \fn QSet QSet::operator&(const QSet &other) + \internal + + These will go away in Qt 5. +*/ + +/*! + \class QSet::iterator + \since 4.2 + \brief The QSet::iterator class provides an STL-style non-const iterator for QSet. + + QSet features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators are more + low-level and more cumbersome to use; on the other hand, they are + slightly faster and, for developers who already know STL, have + the advantage of familiarity. + + QSet::iterator allows you to iterate over a QSet and to remove + items (using QSet::erase()) while you iterate. (QSet doesn't let + you \e modify a value through an iterator, because that + would potentially require moving the value in the internal hash + table used by QSet.) If you want to iterate over a const QSet, + you should use QSet::const_iterator. It is generally good + practice to use QSet::const_iterator on a non-const QSet as well, + unless you need to change the QSet through the iterator. Const + iterators are slightly faster, and can improve code readability. + + QSet\::iterator allows you to iterate over a QSet\ and + modify it as you go (using QSet::erase()). However, + + The default QSet::iterator constructor creates an uninitialized + iterator. You must initialize it using a function like + QSet::begin(), QSet::end(), or QSet::insert() before you can + start iterating. Here's a typical loop that prints all the items + stored in a set: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 + + Here's a loop that removes certain items (all those that start + with 'J') from a set while iterating: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 + + STL-style iterators can be used as arguments to \l{generic + algorithms}. For example, here's how to find an item in the set + using the qFind() algorithm: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 + + Multiple iterators can be used on the same set. However, you may + not attempt to modify the container while iterating on it. + + \sa QSet::const_iterator, QMutableSetIterator +*/ + +/*! + \class QSet::const_iterator + \brief The QSet::const_iterator class provides an STL-style const iterator for QSet. + \since 4.2 + + QSet features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators are more + low-level and more cumbersome to use; on the other hand, they are + slightly faster and, for developers who already know STL, have + the advantage of familiarity. + + QSet\::const_iterator allows you to iterate over a QSet. + If you want to modify the QSet as you iterate over it, you must + use QSet::iterator instead. It is generally good practice to use + QSet::const_iterator on a non-const QSet as well, unless you need + to change the QSet through the iterator. Const iterators are + slightly faster, and can improve code readability. + + The default QSet::const_iterator constructor creates an + uninitialized iterator. You must initialize it using a function + like QSet::begin(), QSet::end(), or QSet::insert() before you can + start iterating. Here's a typical loop that prints all the items + stored in a set: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 + + STL-style iterators can be used as arguments to \l{generic + algorithms}. For example, here's how to find an item in the set + using the qFind() algorithm: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 + + Multiple iterators can be used on the same set. However, you may + not attempt to modify the container while iterating on it. + + \sa QSet::iterator, QSetIterator +*/ + +/*! + \fn QSet::iterator::iterator() + \fn QSet::const_iterator::const_iterator() + + Constructs an uninitialized iterator. + + Functions like operator*() and operator++() should not be called + on an uninitialized iterator. Use operator=() to assign a value + to it before using it. + + \sa QSet::begin(), QSet::end() +*/ + +/*! + \fn QSet::iterator::iterator(typename Hash::iterator i) + \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i) + + \internal +*/ + +/*! + \typedef QSet::iterator::iterator_category + \typedef QSet::const_iterator::iterator_category + + Synonyms for \e {std::bidirectional_iterator_tag} indicating + these iterators are bidirectional iterators. + */ + +/*! + \typedef QSet::iterator::difference_type + \typedef QSet::const_iterator::difference_type + + \internal +*/ + +/*! + \typedef QSet::iterator::value_type + \typedef QSet::const_iterator::value_type + + \internal +*/ + +/*! + \typedef QSet::iterator::pointer + \typedef QSet::const_iterator::pointer + + \internal +*/ + +/*! + \typedef QSet::iterator::reference + \typedef QSet::const_iterator::reference + + \internal +*/ + +/*! + \fn QSet::iterator::iterator(const iterator &other) + \fn QSet::const_iterator::const_iterator(const const_iterator &other) + + Constructs a copy of \a other. +*/ + +/*! + \fn QSet::const_iterator::const_iterator(const iterator &other) + \since 4.2 + \overload + + Constructs a copy of \a other. +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator=(const iterator &other) + \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other) + + Assigns \a other to this iterator. +*/ + +/*! + \fn const T &QSet::iterator::operator*() const + \fn const T &QSet::const_iterator::operator*() const + + Returns a reference to the current item. + + \sa operator->() +*/ + +/*! + \fn const T *QSet::iterator::operator->() const + \fn const T *QSet::const_iterator::operator->() const + + Returns a pointer to the current item. + + \sa operator*() +*/ + +/*! + \fn bool QSet::iterator::operator==(const iterator &other) const + \fn bool QSet::const_iterator::operator==(const const_iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! + \fn bool QSet::iterator::operator==(const const_iterator &other) const + \fn bool QSet::iterator::operator!=(const const_iterator &other) const + + \overload +*/ + +/*! + \fn bool QSet::iterator::operator!=(const iterator &other) const + \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator++() + \fn QSet::const_iterator &QSet::const_iterator::operator++() + + The prefix ++ operator (\c{++it}) advances the iterator to the + next item in the set and returns an iterator to the new current + item. + + Calling this function on QSet::constEnd() leads to + undefined results. + + \sa operator--() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator++(int) + \fn QSet::const_iterator QSet::const_iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{it++}) advances the iterator to the + next item in the set and returns an iterator to the previously + current item. +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator--() + \fn QSet::const_iterator &QSet::const_iterator::operator--() + + The prefix -- operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QSet::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator--(int) + \fn QSet::const_iterator QSet::const_iterator::operator--(int) + + \overload + + The postfix -- operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator+(int j) const + \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. (If \a j is negative, the iterator goes backward.) + + This operation can be slow for large \a j values. + + \sa operator-() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator-(int j) const + \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. (If \a j is negative, the iterator goes forward.) + + This operation can be slow for large \a j values. + + \sa operator+() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator+=(int j) + \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + This operation can be slow for large \a j values. + + \sa operator-=(), operator+() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator-=(int j) + \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j) + + Makes the iterator go back by \a j items. (If \a j is negative, + the iterator goes forward.) + + This operation can be slow for large \a j values. + + \sa operator+=(), operator-() +*/ + +/*! \fn QList QSet::toList() const + + Returns a new QList containing the elements in the set. The + order of the elements in the QList is undefined. + + Example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 + + \sa fromList(), QList::fromSet(), qSort() +*/ + +/*! \fn QList QSet::values() const + + Returns a new QList containing the elements in the set. The + order of the elements in the QList is undefined. + + This is the same as toList(). + + \sa fromList(), QList::fromSet(), qSort() +*/ + + +/*! \fn QSet QSet::fromList(const QList &list) + + Returns a new QSet object containing the data contained in \a + list. Since QSet doesn't allow duplicates, the resulting QSet + might be smaller than the \a list, because QList can contain + duplicates. + + Example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 + + \sa toList(), QList::toSet() +*/ + +/*! + \fn QDataStream &operator<<(QDataStream &out, const QSet &set) + \relates QSet + + Writes the \a set to stream \a out. + + This function requires the value type to implement \c operator<<(). + + \sa \link datastreamformat.html Format of the QDataStream operators \endlink +*/ + +/*! + \fn QDataStream &operator>>(QDataStream &in, QSet &set) + \relates QSet + + Reads a set from stream \a in into \a set. + + This function requires the value type to implement \c operator>>(). + + \sa \link datastreamformat.html Format of the QDataStream operators \endlink +*/ diff --git a/doc/src/classes/qsignalspy.qdoc b/doc/src/classes/qsignalspy.qdoc new file mode 100644 index 0000000..4ee7590 --- /dev/null +++ b/doc/src/classes/qsignalspy.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSignalSpy + \inmodule QtTest + + \brief The QSignalSpy class enables introspection of signal emission. + + QSignalSpy can connect to any signal of any object and records its emission. + QSignalSpy itself is a list of QVariant lists. Each emission of the signal + will append one item to the list, containing the arguments of the signal. + + The following example records all signal emissions for the \c clicked() signal + of a QCheckBox: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 + + \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a + list of QVariant objects. The \c clicked() signal has a single bool argument, + which is stored as the first entry in the list of arguments. + + The example below catches a signal from a custom object: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 + + \bold {Note:} Non-standard data types need to be registered, using + the qRegisterMetaType() function, before you can create a + QSignalSpy. For example: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 + + To retrieve the \c QModelIndex, you can use qvariant_cast: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 + */ + +/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) + + Constructs a new QSignalSpy that listens for emissions of the \a signal + from the QObject \a object. Neither \a signal nor \a object can be null. + + Example: + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 +*/ + +/*! \fn QSignalSpy::isValid() const + + Returns true if the signal spy listens to a valid signal, otherwise false. +*/ + +/*! \fn QSignalSpy::signal() const + + Returns the normalized signal the spy is currently listening to. +*/ + +/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a) + \internal +*/ + diff --git a/doc/src/classes/qsizepolicy.qdoc b/doc/src/classes/qsizepolicy.qdoc new file mode 100644 index 0000000..c74beb8 --- /dev/null +++ b/doc/src/classes/qsizepolicy.qdoc @@ -0,0 +1,522 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSizePolicy + \brief The QSizePolicy class is a layout attribute describing horizontal + and vertical resizing policy. + + \ingroup appearance + \ingroup geomanagement + + The size policy of a widget is an expression of its willingness to + be resized in various ways, and affects how the widget is treated + by the \l{Layout Management}{layout engine}. Each widget returns a + QSizePolicy that describes the horizontal and vertical resizing + policy it prefers when being laid out. You can change this for + a specific widget by changing its QWidget::sizePolicy property. + + QSizePolicy contains two independent QSizePolicy::Policy values + and two stretch factors; one describes the widgets's horizontal + size policy, and the other describes its vertical size policy. It + also contains a flag to indicate whether the height and width of + its preferred size are related. + + The horizontal and vertical policies can be set in the + constructor, and altered using the setHorizontalPolicy() and + setVerticalPolicy() functions. The stretch factors can be set + using the setHorizontalStretch() and setVerticalStretch() + functions. The flag indicating whether the widget's + \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a + menu bar or a word-wrapping label) can be set using the + setHeightForWidth() function. + + The current size policies and stretch factors be retrieved using + the horizontalPolicy(), verticalPolicy(), horizontalStretch() and + verticalStretch() functions. Alternatively, use the transpose() + function to swap the horizontal and vertical policies and + stretches. The hasHeightForWidth() function returns the current + status of the flag indicating the size hint dependencies. + + Use the expandingDirections() function to determine whether the + associated widget can make use of more space than its + \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as + find out in which directions it can expand. + + Finally, the QSizePolicy class provides operators comparing this + size policy to a given policy, as well as a QVariant operator + storing this QSizePolicy as a QVariant object. + + \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy, + QLayoutItem::sizeHint() +*/ + +/*! + \enum QSizePolicy::PolicyFlag + + These flags are combined together to form the various \l{Policy} + values: + + \value GrowFlag The widget can grow beyond its size hint if necessary. + \value ExpandFlag The widget should get as much space as possible. + \value ShrinkFlag The widget can shrink below its size hint if necessary. + \value IgnoreFlag The widget's size hint is ignored. The widget will get + as much space as possible. + + \sa Policy +*/ + +/*! + \enum QSizePolicy::Policy + + This enum describes the various per-dimension sizing types used + when constructing a QSizePolicy. + + \value Fixed The QWidget::sizeHint() is the only acceptable + alternative, so the widget can never grow or shrink (e.g. the + vertical direction of a push button). + + \value Minimum The sizeHint() is minimal, and sufficient. The + widget can be expanded, but there is no advantage to it being + larger (e.g. the horizontal direction of a push button). + It cannot be smaller than the size provided by sizeHint(). + + \value Maximum The sizeHint() is a maximum. The widget can be + shrunk any amount without detriment if other widgets need the + space (e.g. a separator line). + It cannot be larger than the size provided by sizeHint(). + + \value Preferred The sizeHint() is best, but the widget can be + shrunk and still be useful. The widget can be expanded, but there + is no advantage to it being larger than sizeHint() (the default + QWidget policy). + + \value Expanding The sizeHint() is a sensible size, but the + widget can be shrunk and still be useful. The widget can make use + of extra space, so it should get as much space as possible (e.g. + the horizontal direction of a horizontal slider). + + \value MinimumExpanding The sizeHint() is minimal, and sufficient. + The widget can make use of extra space, so it should get as much + space as possible (e.g. the horizontal direction of a horizontal + slider). + + \value Ignored The sizeHint() is ignored. The widget will get as + much space as possible. + + \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy() +*/ + +/*! + \fn QSizePolicy::QSizePolicy() + + Constructs a QSizePolicy object with \l Fixed as its horizontal + and vertical policies. + + The policies can be altered using the setHorizontalPolicy() and + setVerticalPolicy() functions. Use the setHeightForWidth() + function if the preferred height of the widget is dependent on the + width of the widget (for example, a QLabel with line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch() +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical) + + Constructs a QSizePolicy object with the given \a horizontal and + \a vertical policies, and DefaultType as the control type. + + Use setHeightForWidth() if the preferred height of the widget is + dependent on the width of the widget (for example, a QLabel with + line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch() +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type) + \since 4.3 + + Constructs a QSizePolicy object with the given \a horizontal and + \a vertical policies, and the specified control \a type. + + Use setHeightForWidth() if the preferred height of the widget is + dependent on the width of the widget (for example, a QLabel with + line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch(), controlType() +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const + + Returns the horizontal component of the size policy. + + \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch() +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const + + Returns the vertical component of the size policy. + + \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch() +*/ + +/*! + \fn void QSizePolicy::setHorizontalPolicy(Policy policy) + + Sets the horizontal component to the given \a policy. + + \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch() +*/ + +/*! + \fn void QSizePolicy::setVerticalPolicy(Policy policy) + + Sets the vertical component to the given \a policy. + + \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch() +*/ + +/*! + \fn Qt::Orientations QSizePolicy::expandingDirections() const + + Returns whether a widget can make use of more space than the + QWidget::sizeHint() function indicates. + + A value of Qt::Horizontal or Qt::Vertical means that the widget + can grow horizontally or vertically (i.e., the horizontal or + vertical policy is \l Expanding or \l MinimumExpanding), whereas + Qt::Horizontal | Qt::Vertical means that it can grow in both + dimensions. + + \sa horizontalPolicy(), verticalPolicy() +*/ + +/*! + \fn ControlType QSizePolicy::controlType() const + \since 4.3 + + Returns the control type associated with the widget for which + this size policy applies. +*/ + +/*! + \fn void QSizePolicy::setControlType(ControlType type) + \since 4.3 + + Sets the control type associated with the widget for which this + size policy applies to \a type. + + The control type specifies the type of the widget for which this + size policy applies. It is used by some styles, notably + QMacStyle, to insert proper spacing between widgets. For example, + the Mac OS X Aqua guidelines specify that push buttons should be + separated by 12 pixels, whereas vertically stacked radio buttons + only require 6 pixels. + + \sa QStyle::layoutSpacing() +*/ + +/*! + \fn void QSizePolicy::setHeightForWidth(bool dependent) + + Sets the flag determining whether the widget's preferred height + depends on its width, to \a dependent. + + \sa hasHeightForWidth() +*/ + +/*! + \fn bool QSizePolicy::hasHeightForWidth() const + + Returns true if the widget's preferred height depends on its + width; otherwise returns false. + + \sa setHeightForWidth() +*/ + +/*! + \fn bool QSizePolicy::operator==(const QSizePolicy &other) const + + Returns true if this policy is equal to \a other; otherwise + returns false. + + \sa operator!=() +*/ + +/*! + \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const + + Returns true if this policy is different from \a other; otherwise + returns false. + + \sa operator==() +*/ + +/*! + \fn int QSizePolicy::horizontalStretch() const + + Returns the horizontal stretch factor of the size policy. + + \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy() +*/ + +/*! + \fn int QSizePolicy::verticalStretch() const + + Returns the vertical stretch factor of the size policy. + + \sa setVerticalStretch(), horizontalStretch(), verticalPolicy() +*/ + +/*! + \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor) + + Sets the horizontal stretch factor of the size policy to the given \a + stretchFactor. + + \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy() +*/ + +/*! + \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor) + + Sets the vertical stretch factor of the size policy to the given + \a stretchFactor. + + \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy() +*/ + +/*! + \fn void QSizePolicy::transpose() + + Swaps the horizontal and vertical policies and stretches. +*/ + +/*! + \enum QSizePolicy::ControlType + \since 4.3 + + This enum specifies the different types of widgets in terms of + layout interaction: + + \value DefaultType The default type, when none is specified. + \value ButtonBox A QDialogButtonBox instance. + \value CheckBox A QCheckBox instance. + \value ComboBox A QComboBox instance. + \value Frame A QFrame instance. + \value GroupBox A QGroupBox instance. + \value Label A QLabel instance. + \value Line A QFrame instance with QFrame::HLine or QFrame::VLine. + \value LineEdit A QLineEdit instance. + \value PushButton A QPushButton instance. + \value RadioButton A QRadioButton instance. + \value Slider A QAbstractSlider instance. + \value SpinBox A QAbstractSpinBox instance. + \value TabWidget A QTabWidget instance. + \value ToolButton A QToolButton instance. + + \sa setControlType(), controlType() +*/ + +#ifdef QT3_SUPPORT +/*! + \typedef QSizePolicy::SizeType + \compat + + Use the QSizePolicy::Policy enum instead. +*/ + +/*! + \enum QSizePolicy::ExpandData + \compat + + Use the Qt::Orientations enum instead. + + \value NoDirection Use 0 instead. + \value Horizontally Use Qt::Horizontal instead. + \value Vertically Use Qt::Vertical instead. + \value BothDirections Use Qt::Horizontal | Qt::Vertical instead. +*/ + +/*! + \fn bool QSizePolicy::mayShrinkHorizontally() const + + Use the horizontalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayShrinkHorizontally(); + \newcode + bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayShrinkVertically() const + + Use the verticalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayShrinkVertically(); + \newcode + bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayGrowHorizontally() const + + Use the horizontalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayGrowHorizontally(); + \newcode + bool policy = horizontalPolicy() & QSizePolicy::GrowFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayGrowVertically() const + + Use the verticalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayGrowVertically(); + \newcode + bool policy = verticalPolicy() & QSizePolicy::GrowFlag; + \endcode +*/ + +/*! + \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const + + Use expandingDirections() instead. +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent) + + Use the QSizePolicy() constructor and the setHeightForWidth() + function instead. + + \oldcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent); + \newcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical); + policy->setHeightForWidth(dependent); + \endcode +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch, + uchar verticalStretch, bool dependent) + + Use the QSizePolicy() constructor and call the + setHorizontalStretch(), setVerticalStretch(), and + setHeightForWidth() functions instead. + + \oldcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical, + horizontalStretch, verticalStretch, + dependent); + \newcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical); + policy->setHorizontalStretch(horizontalStretch); + policy->setVerticalStretch(verticalStretch); + policy->setHeightForWidth(dependent); + \endcode +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::horData() const + + Use horizontalPolicy() instead. +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::verData() const + + Use verticalPolicy() instead. +*/ + +/*! + \fn void QSizePolicy::setHorData(Policy policy) + + Use setHorizontalPolicy() instead. +*/ + +/*! + \fn void QSizePolicy::setVerData(Policy policy) + + Use setVerticalPolicy() instead. +*/ + +/*! + \fn uint QSizePolicy::horStretch() const + + Use horizontalStretch() instead. +*/ + +/*! + \fn uint QSizePolicy::verStretch() const + + Use verticalStretch() instead. +*/ + +/*! + \fn void QSizePolicy::setHorStretch(uchar stretch) + + Use setHorizontalStretch() instead. +*/ + +/*! + \fn void QSizePolicy::setVerStretch(uchar stretch) + + Use setVerticalStretch() instead. +*/ +#endif diff --git a/doc/src/classes/qtdesigner-api.qdoc b/doc/src/classes/qtdesigner-api.qdoc new file mode 100644 index 0000000..d7c47b1 --- /dev/null +++ b/doc/src/classes/qtdesigner-api.qdoc @@ -0,0 +1,1413 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QDesignerMemberSheetExtension + + \brief The QDesignerMemberSheetExtension class allows you to + manipulate a widget's member functions which is displayed when + configuring connections using Qt Designer's mode for editing + signals and slots. + + \inmodule QtDesigner + + QDesignerMemberSheetExtension is a collection of functions that is + typically used to query a widget's member functions, and to + manipulate the member functions' appearance in \QD's signals and + slots editing mode. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 + + When implementing a custom widget plugin, a pointer to \QD's + current QDesignerFormEditorInterface object (\c formEditor in the + example above) is provided by the + QDesignerCustomWidgetInterface::initialize() function's parameter. + + The member sheet (and any other extension), can be retrieved by + querying \QD's extension manager using the qt_extension() + function. When you want to release the extension, you only need to + delete the pointer. + + All widgets have a default member sheet used in \QD's signals and + slots editing mode with the widget's member functions. But + QDesignerMemberSheetExtension also provides an interface for + creating custom member sheet extensions. + + \warning \QD uses the QDesignerMemberSheetExtension to facilitate + the signal and slot editing mode. Whenever a connection between + two widgets is requested, \QD will query for the widgets' member + sheet extensions. If a widget has an implemented member sheet + extension, this extension will override the default member sheet. + + To create a member sheet extension, your extension class must + inherit from both QObject and QDesignerMemberSheetExtension. Then, + since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 + + This enables \QD to use qobject_cast() to query for + supported interfaces using nothing but a QObject pointer. + + In \QD the extensions are not created until they are + required. For that reason, when implementing a member sheet + extension, you must also create a QExtensionFactory, i.e a class + that is able to make an instance of your extension, and register + it using \QD's \l {QExtensionManager}{extension manager}. + + When a widget's member sheet extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a member sheet + extension for that widget, is found. This factory will then make + an instance of the extension. If no such factory is found, \QD + will use the default member sheet. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and + QDesignerTaskMenuExtension. \QD's behavior is the same whether the + requested extension is associated with a multi page container, a + member sheet, a property sheet or a task menu. + + The QExtensionFactory class provides a standard extension + factory, and can also be used as an interface for custom + extension factories. You can either create a new + QExtensionFactory and reimplement the + QExtensionFactory::createExtension() function. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a member sheet extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 + + For a complete example using an extension class, see \l + {designer/taskmenuextension}{Task Menu Extension example}. The + example shows how to create a custom widget plugin for Qt + Designer, and how to to use the QDesignerTaskMenuExtension class + to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() + + Destroys the member sheet extension. +*/ + +/*! + \fn int QDesignerMemberSheetExtension::count() const + + Returns the extension's number of member functions. +*/ + +/*! + \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const + + Returns the index of the member function specified by the given \a + name. + + \sa memberName() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::memberName(int index) const + + Returns the name of the member function with the given \a index. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const + + Returns the name of the member group specified for the function + with the given \a index. + + \sa indexOf(), setMemberGroup() +*/ + +/*! + \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) + + Sets the member group of the member function with the given \a + index, to \a group. + + \sa indexOf(), memberGroup() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::isVisible(int index) const + + Returns true if the member function with the given \a index is + visible in \QD's signal and slot editor, otherwise false. + + \sa indexOf(), setVisible() +*/ + +/*! + \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) + + If \a visible is true, the member function with the given \a index + is visible in \QD's signals and slots editing mode; otherwise the + member function is hidden. + + \sa indexOf(), isVisible() +*/ + +/*! + \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const + + Returns true if the member function with the given \a index is a + signal, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::isSlot(int index) const + + Returns true if the member function with the given \a index is a + slot, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const + + Returns true if the member function with the given \a index is + inherited from QWidget, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const + + Returns the name of the class in which the member function with + the given \a index is declared. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::signature(int index) const + + Returns the signature of the member function with the given \a + index. + + \sa indexOf() +*/ + +/*! + \fn QList QDesignerMemberSheetExtension::parameterTypes(int index) const + + Returns the parameter types of the member function with the given + \a index, as a QByteArray list. + + \sa indexOf(), parameterNames() +*/ + +/*! + \fn QList QDesignerMemberSheetExtension::parameterNames(int index) const + + Returns the parameter names of the member function with the given + \a index, as a QByteArray list. + + \sa indexOf(), parameterTypes() +*/ + + +// Doc: Interface only + +/*! + \class QDesignerLayoutDecorationExtension + \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. + \inmodule QtDesigner + \internal +*/ + +/*! + \enum QDesignerLayoutDecorationExtension::InsertMode + + This enum describes the modes that are used to insert items into a layout. + + \value InsertWidgetMode Widgets are inserted into empty cells in a layout. + \value InsertRowMode Whole rows are inserted into a vertical or grid layout. + \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. +*/ + +/*! + \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() + + Destroys the extension. +*/ + +/*! + \fn virtual QList QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const + + Returns the widgets that are managed by the given \a layout. + + \sa insertWidget(), removeWidget() +*/ + +/*! + \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const + + Returns the rectangle covered by the item at the given \a index in the layout. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const + + Returns the index of the specified \a widget in the layout. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const + + Returns the index of the specified layout \a item. +*/ + +/*! + \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const + + Returns the current insertion mode. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::currentIndex() const + + Returns the current index in the layout. +*/ + +/*! + \fn QPair QDesignerLayoutDecorationExtension::currentCell() const + + Returns a pair containing the row and column of the current cell in the layout. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair &cell) + + Inserts the given \a widget into the specified \a cell in the layout. + + \sa removeWidget() +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) + + Removes the specified \a widget from the layout. + + \sa insertWidget() +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertRow(int row) + + Inserts a new row into the form at the position specified by \a row. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) + + Inserts a new column into the form at the position specified by \a column. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::simplify() + + Simplifies the layout by removing unnecessary empty rows and columns, and by changing the + number of rows or columns spanned by widgets. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const + + Returns the index of the item in the layout that covers the given \a position. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const + + Returns the item in the layout that occupies the specified \a row and \a column in the layout. + + Currently, this only applies to grid layouts. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) + + Adjusts the indicator for the item specified by \a index so that + it lies at the given \a position on the form. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerContainerExtension + \brief The QDesignerContainerExtension class allows you to add pages to + a custom multi-page container in Qt Designer's workspace. + \inmodule QtDesigner + + QDesignerContainerExtension provide an interface for creating + custom container extensions. A container extension consists of a + collection of functions that \QD needs to manage a multi-page + container plugin, and a list of the container's pages. + + \image containerextension-example.png + + \warning This is \e not an extension for container plugins in + general, only custom \e multi-page containers. + + To create a container extension, your extension class must inherit + from both QObject and QDesignerContainerExtension. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 + + Since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + You must reimplement several functions to enable \QD to manage a + custom multi-page container widget: \QD uses count() to keep track + of the number pages in your container, widget() to return the page + at a given index in the list of the container's pages, and + currentIndex() to return the list index of the selected page. \QD + uses the addWidget() function to add a given page to the + container, expecting it to be appended to the list of pages, while + it expects the insertWidget() function to add a given page to the + container by inserting it at a given index. + + In \QD the extensions are not created until they are + required. For that reason you must also create a + QExtensionFactory, i.e a class that is able to make an instance of + your extension, and register it using \QD's \l + {QExtensionManager}{extension manager}. + + When a container extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a container + extension, is found. This factory will then create the extension + for the plugin. + + There are four available types of extensions in \QD: + QDesignerContainerExtension , QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. + \QD's behavior is the same whether the requested extension is + associated with a multi page container, a member sheet, a property + sheet or a task menu. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a container extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 + + For a complete example using the QDesignerContainerExtension + class, see the \l {designer/containerextension}{Container + Extension example}. The example shows how to create a custom + multi-page plugin for \QD. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerContainerExtension::~QDesignerContainerExtension() + + Destroys the extension. +*/ + +/*! + \fn int QDesignerContainerExtension::count() const + + Returns the number of pages in the container. +*/ + +/*! + \fn QWidget *QDesignerContainerExtension::widget(int index) const + + Returns the page at the given \a index in the extension's list of + pages. + + \sa addWidget(), insertWidget() +*/ + +/*! + \fn int QDesignerContainerExtension::currentIndex() const + + Returns the index of the currently selected page in the + container. + + \sa setCurrentIndex() +*/ + +/*! + \fn void QDesignerContainerExtension::setCurrentIndex(int index) + + Sets the currently selected page in the container to be the + page at the given \a index in the extension's list of pages. + + \sa currentIndex() +*/ + +/*! + \fn void QDesignerContainerExtension::addWidget(QWidget *page) + + Adds the given \a page to the container by appending it to the + extension's list of pages. + + \sa insertWidget(), remove(), widget() +*/ + +/*! + \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) + + Adds the given \a page to the container by inserting it at the + given \a index in the extension's list of pages. + + \sa addWidget(), remove(), widget() +*/ + +/*! + \fn void QDesignerContainerExtension::remove(int index) + + Removes the page at the given \a index from the extension's list + of pages. + + \sa addWidget(), insertWidget() +*/ + + +// Doc: Interface only + +/*! + \class QDesignerTaskMenuExtension + \brief The QDesignerTaskMenuExtension class allows you to add custom + menu entries to Qt Designer's task menu. + \inmodule QtDesigner + + QDesignerTaskMenuExtension provides an interface for creating + custom task menu extensions. It is typically used to create task + menu entries that are specific to a plugin in \QD. + + \QD uses the QDesignerTaskMenuExtension to feed its task + menu. Whenever a task menu is requested, \QD will query + for the selected widget's task menu extension. + + \image taskmenuextension-example-faded.png + + A task menu extension is a collection of QActions. The actions + appear as entries in the task menu when the plugin with the + specified extension is selected. The image above shows the custom + \gui {Edit State...} action which appears in addition to \QD's + default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. + + To create a custom task menu extension, your extension class must + inherit from both QObject and QDesignerTaskMenuExtension. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 + + Since we are implementing an interface, we must ensure that it + is made known to the meta-object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + You must reimplement the taskActions() function to return a list + of actions that will be included in \QD task menu. Optionally, you + can reimplement the preferredEditAction() function to set the + action that is invoked when selecting your plugin and pressing + \key F2. The preferred edit action must be one of the actions + returned by taskActions() and, if it's not defined, pressing the + \key F2 key will simply be ignored. + + In \QD, extensions are not created until they are required. A + task menu extension, for example, is created when you click the + right mouse button over a widget in \QD's workspace. For that + reason you must also construct an extension factory, using either + QExtensionFactory or a subclass, and register it using \QD's + \l {QExtensionManager}{extension manager}. + + When a task menu extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until it finds one that is able to create a task menu + extension for the selected widget. This factory will then make an + instance of the extension. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. + \QD's behavior is the same whether the requested extension is + associated with a container, a member sheet, a property sheet or a + task menu. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a task menu extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 + + For a complete example using the QDesignerTaskMenuExtension class, + see the \l {designer/taskmenuextension}{Task Menu Extension + example}. The example shows how to create a custom widget plugin + for \QD, and how to to use the QDesignerTaskMenuExtension + class to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() + + Destroys the task menu extension. +*/ + +/*! + \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const + + Returns the action that is invoked when selecting a plugin with + the specified extension and pressing \key F2. + + The action must be one of the actions returned by taskActions(). +*/ + +/*! + \fn QList QDesignerTaskMenuExtension::taskActions() const + + Returns the task menu extension as a list of actions which will be + included in \QD's task menu when a plugin with the specified + extension is selected. + + The function must be reimplemented to add actions to the list. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerCustomWidgetCollectionInterface + + \brief The QDesignerCustomWidgetCollectionInterface class allows + you to include several custom widgets in one single library. + + \inmodule QtDesigner + + When implementing a custom widget plugin, you build it as a + separate library. If you want to include several custom widget + plugins in the same library, you must in addition subclass + QDesignerCustomWidgetCollectionInterface. + + QDesignerCustomWidgetCollectionInterface contains one single + function returning a list of the collection's + QDesignerCustomWidgetInterface objects. For example, if you have + several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and + \c CustomWidgetThree, the class definition may look like this: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 + + In the class constructor you add the interfaces to your custom + widgets to the list which you return in the customWidgets() + function: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 + + Note that instead of exporting each custom widget plugin using the + Q_EXPORT_PLUGIN2() macro, you export the entire collection. The + Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct + the custom widgets. Without this macro, there is no way for \QD to + use them. + + \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for + Qt Designer} +*/ + +/*! + \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { + + Destroys the custom widget collection interface. +*/ + +/*! + \fn QList QDesignerCustomWidgetCollectionInterface::customWidgets() const + + Returns a list of interfaces to the collection's custom widgets. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerCustomWidgetInterface + + \brief The QDesignerCustomWidgetInterface class enables Qt Designer + to access and construct custom widgets. + + \inmodule QtDesigner + + QDesignerCustomWidgetInterface provides a custom widget with an + interface. The class contains a set of functions that must be subclassed + to return basic information about the widget, such as its class name and + the name of its header file. Other functions must be implemented to + initialize the plugin when it is loaded, and to construct instances of + the custom widget for \QD to use. + + When implementing a custom widget you must subclass + QDesignerCustomWidgetInterface to expose your widget to \QD. For + example, this is the declaration for the plugin used in the + \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that + enables an analog clock custom widget to be used by \QD: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 + + Note that the only part of the class definition that is specific + to this particular custom widget is the class name. In addition, + since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + After \QD loads a custom widget plugin, it calls the interface's + initialize() function to enable it to set up any resources that it + may need. This function is called with a QDesignerFormEditorInterface + parameter that provides the plugin with a gateway to all of \QD's API. + + \QD constructs instances of the custom widget by calling the plugin's + createWidget() function with a suitable parent widget. Plugins must + construct and return an instance of a custom widget with the specified + parent widget. + + In the implementation of the class you must remember to export + your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() + macro. For example, if a library called \c libcustomwidgetplugin.so + (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget + class called \c MyCustomWidget, we can export it by adding the + following line to the file containing the plugin implementation: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 + + This macro ensures that \QD can access and construct the custom widget. + Without this macro, there is no way for \QD to use it. + + When implementing a custom widget plugin, you build it as a + separate library. If you want to include several custom widget + plugins in the same library, you must in addition subclass + QDesignerCustomWidgetCollectionInterface. + + \warning If your custom widget plugin contains QVariant + properties, be aware that only the following \l + {QVariant::Type}{types} are supported: + + \list + \o QVariant::ByteArray + \o QVariant::Bool + \o QVariant::Color + \o QVariant::Cursor + \o QVariant::Date + \o QVariant::DateTime + \o QVariant::Double + \o QVariant::Int + \o QVariant::Point + \o QVariant::Rect + \o QVariant::Size + \o QVariant::SizePolicy + \o QVariant::String + \o QVariant::Time + \o QVariant::UInt + \endlist + + For a complete example using the QDesignerCustomWidgetInterface + class, see the \l {designer/customwidgetplugin}{Custom Widget + Example}. The example shows how to create a custom widget plugin + for \QD. + + \sa QDesignerCustomWidgetCollectionInterface {Creating Custom + Widgets for Qt Designer} +*/ + +/*! + \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() + + Destroys the custom widget interface. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::name() const + + Returns the class name of the custom widget supplied by the interface. + + The name returned \e must be identical to the class name used for the + custom widget. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::group() const + + Returns the name of the group to which the custom widget belongs. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::toolTip() const + + Returns a short description of the widget that can be used by \QD + in a tool tip. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::whatsThis() const + + Returns a description of the widget that can be used by \QD in + "What's This?" help for the widget. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::includeFile() const + + Returns the path to the include file that \l uic uses when + creating code for the custom widget. +*/ + +/*! + \fn QIcon QDesignerCustomWidgetInterface::icon() const + + Returns the icon used to represent the custom widget in \QD's + widget box. +*/ + +/*! + \fn bool QDesignerCustomWidgetInterface::isContainer() const + + Returns true if the custom widget is intended to be used as a + container; otherwise returns false. + + Most custom widgets are not used to hold other widgets, so their + implementations of this function will return false, but custom + containers will return true to ensure that they behave correctly + in \QD. +*/ + +/*! + \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) + + Returns a new instance of the custom widget, with the given \a + parent. +*/ + +/*! + \fn bool QDesignerCustomWidgetInterface::isInitialized() const + + Returns true if the widget has been initialized; otherwise returns + false. + + \sa initialize() +*/ + +/*! + \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) + + Initializes the widget for use with the specified \a formEditor + interface. + + \sa isInitialized() +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::domXml() const + + Returns the XML that is used to describe the custom widget's + properties to \QD. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::codeTemplate() const + + This function is reserved for future use by \QD. + + \omit + Returns the code template that \QD includes in forms that contain + the custom widget when they are saved. + \endomit +*/ + +/*! + \macro QDESIGNER_WIDGET_EXPORT + \relates QDesignerCustomWidgetInterface + \since 4.1 + + This macro is used when defining custom widgets to ensure that they are + correctly exported from plugins for use with \QD. + + On some platforms, the symbols required by \QD to create new widgets + are removed from plugins by the build system, making them unusable. + Using this macro ensures that the symbols are retained on those platforms, + and has no side effects on other platforms. + + For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} + example exports a custom widget class with the following declaration: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 + \dots + \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 + + \sa {Creating Custom Widgets for Qt Designer} +*/ + + +// Doc: Abstract class + +/*! + \class QDesignerDnDItemInterface + \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items + during a drag and drop operation. + \inmodule QtDesigner + \internal +*/ + +/*! + \enum QDesignerDnDItemInterface::DropType + + This enum describes the result of a drag and drop operation. + + \value MoveDrop The item was moved. + \value CopyDrop The item was copied. +*/ + +/*! + \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() + + Constructs a new interface to a drag and drop item. +*/ + +/*! + \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() + + Destroys the interface to the item. +*/ + +/*! + \fn DomUI *QDesignerDnDItemInterface::domUi() const + + Returns a user interface object for the item. +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::widget() const + + Returns the widget being copied or moved in the drag and drop operation. + + \sa source() +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::decoration() const + + Returns the widget used to represent the item. +*/ + +/*! + \fn QPoint QDesignerDnDItemInterface::hotSpot() const + + Returns the cursor's hotspot. + + \sa QDrag::hotSpot() +*/ + +/*! + \fn DropType QDesignerDnDItemInterface::type() const + + Returns the type of drag and drop operation in progress. +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::source() const + + Returns the widget that is the source of the drag and drop operation; i.e. the original + container of the widget being dragged. + + \sa widget() +*/ + + +// Doc: Abstract class + +/*! + \class QDesignerIconCacheInterface + \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. + \inmodule QtDesigner + \internal +*/ + +/*! + \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) + + Constructs a new interface with the given \a parent. +*/ + +/*! + \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) + + Returns the icon associated with the name specified by \a filePath in the resource + file specified by \a qrcPath. + + If \a qrcPath refers to a valid resource file, the name used for the file path is a path + within those resources; otherwise the file path refers to a local file. + + \sa {The Qt Resource System}, nameToPixmap() +*/ + +/*! + \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) + + Returns the pixmap associated with the name specified by \a filePath in the resource + file specified by \a qrcPath. + + If \a qrcPath refers to a valid resource file, the name used for the file path is a path + within those resources; otherwise the file path refers to a local file. + + \sa {The Qt Resource System}, nameToIcon() +*/ + +/*! + \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const + + Returns the file path associated with the given \a icon. The file path is a path within + an application resources. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const + + Returns the path to the resource file that refers to the specified \a icon. The resource + path refers to a local file. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const + + Returns the file path associated with the given \a pixmap. The file path is a path within + an application resources. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const + + Returns the path to the resource file that refers to the specified \a pixmap. The resource + path refers to a local file. +*/ + +/*! + \fn QList QDesignerIconCacheInterface::pixmapList() const + + Returns a list of pixmaps for the icons provided by the icon cache. +*/ + +/*! + \fn QList QDesignerIconCacheInterface::iconList() const + + Returns a list of icons provided by the icon cache. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const + + Returns a path to a resource specified by the \a filePath within + the resource file located at \a qrcPath. If \a workingDirectory is + a valid path to a directory, the path returned will be relative to + that directory; otherwise an absolute path is returned. + + \omit + ### Needs checking + \endomit +*/ + + +// Doc: Interface only + +/*! + \class QDesignerPropertySheetExtension + + \brief The QDesignerPropertySheetExtension class allows you to + manipulate a widget's properties which is displayed in Qt + Designer's property editor. + + \sa QDesignerDynamicPropertySheetExtension + + \inmodule QtDesigner + + QDesignerPropertySheetExtension provides a collection of functions that + are typically used to query a widget's properties, and to + manipulate the properties' appearance in the property editor. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 + + Note that if you change the value of a property using the + QDesignerPropertySheetExtension::setProperty() function, the undo + stack is not updated. To ensure that a property's value can be + reverted using the undo stack, you must use the + QDesignerFormWindowCursorInterface::setProperty() function, or its + buddy \l + {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, + instead. + + When implementing a custom widget plugin, a pointer to \QD's + current QDesignerFormEditorInterface object (\c formEditor in the + example above) is provided by the + QDesignerCustomWidgetInterface::initialize() function's parameter. + + The property sheet, or any other extension, can be retrieved by + querying \QD's extension manager using the qt_extension() + function. When you want to release the extension, you only need to + delete the pointer. + + All widgets have a default property sheet which populates \QD's + property editor with the widget's properties (i.e the ones defined + with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension + also provides an interface for creating custom property sheet + extensions. + + \warning \QD uses the QDesignerPropertySheetExtension to feed its + property editor. Whenever a widget is selected in its workspace, + \QD will query for the widget's property sheet extension. If the + selected widget has an implemented property sheet extension, this + extension will override the default property sheet. + + To create a property sheet extension, your extension class must + inherit from both QObject and + QDesignerPropertySheetExtension. Then, since we are implementing + an interface, we must ensure that it's made known to the meta + object system using the Q_INTERFACES() macro: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 + + This enables \QD to use qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + In \QD the extensions are not created until they are + required. For that reason, when implementing a property sheet + extension, you must also create a QExtensionFactory, i.e a class + that is able to make an instance of your extension, and register + it using \QD's \l {QExtensionManager}{extension manager}. + + When a property sheet extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a property + sheet extension for the selected widget, is found. This factory + will then make an instance of the extension. If no such factory + can be found, \QD will use the default property sheet. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt + Designer's behavior is the same whether the requested extension is + associated with a multi page container, a member sheet, a property + sheet or a task menu. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a property sheet extension extension as well. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 + + For a complete example using an extension class, see the \l + {designer/taskmenuextension}{Task Menu Extension example}. The + example shows how to create a custom widget plugin for Qt + Designer, and how to to use the QDesignerTaskMenuExtension class + to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() + + Destroys the property sheet extension. +*/ + +/*! + \fn int QDesignerPropertySheetExtension::count() const + + Returns the selected widget's number of properties. +*/ + +/*! + \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const + + Returns the index for a given property \a name. + + \sa propertyName() +*/ + +/*! + \fn QString QDesignerPropertySheetExtension::propertyName(int index) const + + Returns the name of the property at the given \a index. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const + + Returns the property group for the property at the given \a index. + + \QD's property editor supports property groups, i.e. sections of + related properties. A property can be related to a group using the + setPropertyGroup() function. The default group of any property is + the name of the class that defines it. For example, the + QObject::objectName property appears within the QObject property + group. + + \sa indexOf(), setPropertyGroup() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) + + Sets the property group for the property at the given \a index to + \a group. + + Relating a property to a group makes it appear within that group's + section in the property editor. The default property group of any + property is the name of the class that defines it. For example, + the QObject::objectName property appears within the QObject + property group. + + \sa indexOf(), property(), propertyGroup() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::hasReset(int index) const + + Returns true if the property at the given \a index has a reset + button in \QD's property editor, otherwise false. + + \sa indexOf(), reset() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::reset(int index) + + Resets the value of the property at the given \a index, to the + default value. Returns true if a default value could be found, otherwise false. + + \sa indexOf(), hasReset(), isChanged() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isVisible(int index) const + + Returns true if the property at the given \a index is visible in + \QD's property editor, otherwise false. + + \sa indexOf(), setVisible() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) + + If \a visible is true, the property at the given \a index is + visible in \QD's property editor; otherwise the property is + hidden. + + \sa indexOf(), isVisible() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const + + Returns true if the property at the given \a index is an attribute, + which will be \e excluded from the UI file, otherwise false. + + \sa indexOf(), setAttribute() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) + + If \a attribute is true, the property at the given \a index is + made an attribute which will be \e excluded from the UI file; + otherwise it will be included. + + \sa indexOf(), isAttribute() +*/ + +/*! + \fn QVariant QDesignerPropertySheetExtension::property(int index) const + + Returns the value of the property at the given \a index. + + \sa indexOf(), setProperty(), propertyGroup() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) + + Sets the \a value of the property at the given \a index. + + \warning If you change the value of a property using this + function, the undo stack is not updated. To ensure that a + property's value can be reverted using the undo stack, you must + use the QDesignerFormWindowCursorInterface::setProperty() + function, or its buddy \l + {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, + instead. + + \sa indexOf(), property(), propertyGroup() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isChanged(int index) const + + Returns true if the value of the property at the given \a index + differs from the property's default value, otherwise false. + + \sa indexOf(), setChanged(), reset() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) + + Sets whether the property at the given \a index is different from + its default value, or not, depending on the \a changed parameter. + + \sa indexOf(), isChanged() +*/ + +// Doc: Interface only + +/*! + \class QDesignerDynamicPropertySheetExtension + + \brief The QDesignerDynamicPropertySheetExtension class allows you to + manipulate a widget's dynamic properties in Qt Designer's property editor. + + \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} + + \inmodule QtDesigner + \since 4.3 +*/ + +/*! + \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() + + Destroys the dynamic property sheet extension. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const + + Returns true if the widget supports dynamic properties; otherwise returns false. +*/ + +/*! + \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) + + Adds a dynamic property named \a propertyName and sets its value to \a value. + Returns the index of the property if it was added successfully; otherwise returns -1 to + indicate failure. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) + + Removes the dynamic property at the given \a index. + Returns true if the operation succeeds; otherwise returns false. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const + + Returns true if the property at the given \a index is a dynamic property; otherwise + returns false. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const + + Returns true if \a propertyName is a valid, unique name for a dynamic + property; otherwise returns false. + +*/ diff --git a/doc/src/classes/qtendian.qdoc b/doc/src/classes/qtendian.qdoc new file mode 100644 index 0000000..dcffb5d --- /dev/null +++ b/doc/src/classes/qtendian.qdoc @@ -0,0 +1,168 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Endian Conversion Functions + \ingroup architecture + \brief The header provides functions to convert between + little and big endian representations of numbers. +*/ + +/*! + \fn T qFromBigEndian(const uchar *src) + \since 4.3 + \relates + + Reads a big-endian number from memory location \a src and returns the number in the + host byte order representation. + On CPU architectures where the host byte order is little-endian (such as x86) this + will swap the byte order; otherwise it will just read from \a src. + + \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of + integers, e.g., qlong, are not applicable. + + There are no data alignment constraints for \a src. + + \sa qFromLittleEndian() + \sa qToBigEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qFromBigEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from big-endian byte order and returns the number in host byte order + representation of that number. + On CPU architectures where the host byte order is little-endian (such as x86) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn T qFromLittleEndian(const uchar *src) + \since 4.3 + \relates + + Reads a little-endian number from memory location \a src and returns the number in + the host byte order representation. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will swap the byte order; otherwise it will just read from \a src. + + \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of + integers, e.g., qlong, are not applicable. + + There are no data alignment constraints for \a src. + + \sa qFromBigEndian() + \sa qToBigEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qFromLittleEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from little-endian byte order and returns the number in host byte + order representation of that number. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn void qToBigEndian(T src, uchar *dest) + \since 4.3 + \relates + + Writes the number \a src with template type \c{T} to the memory location at \a dest + in big-endian byte order. + + Note that template type \c{T} can only be an integer data type (signed or unsigned). + + There are no data alignment constraints for \a dest. + + \sa qFromBigEndian() + \sa qFromLittleEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qToBigEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from host byte order and returns the number in big-endian byte order + representation of that number. + On CPU architectures where the host byte order is little-endian (such as x86) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn void qToLittleEndian(T src, uchar *dest) + \since 4.3 + \relates + + Writes the number \a src with template type \c{T} to the memory location at \a dest + in little-endian byte order. + + Note that template type \c{T} can only be an integer data type (signed or unsigned). + + There are no data alignment constraints for \a dest. + + \sa qFromBigEndian() + \sa qFromLittleEndian() + \sa qToBigEndian() +*/ +/*! + \fn T qToLittleEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from host byte order and returns the number in little-endian byte + order representation of that number. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ + diff --git a/doc/src/classes/qtestevent.qdoc b/doc/src/classes/qtestevent.qdoc new file mode 100644 index 0000000..2e111b3 --- /dev/null +++ b/doc/src/classes/qtestevent.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QTestEventList + \inmodule QtTest + + \brief The QTestEventList class provides a list of GUI events. + + QTestEventList inherits from QList, and provides + convenience functions for populating the list. + + A QTestEventList can be populated with GUI events that can be + stored as test data for later usage, or be replayed on any + QWidget. + + Example: + \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 + + The example above simulates the user entering the character \c a + followed by a backspace, waiting for 200 milliseconds and + repeating it. +*/ + +/*! \fn QTestEventList::QTestEventList() + + Constructs an empty QTestEventList. +*/ + +/*! \fn QTestEventList::QTestEventList(const QTestEventList &other) + + Constructs a new QTestEventList as a copy of \a other. +*/ + +/*! \fn QTestEventList::~QTestEventList() + + Empties the list and destroys all stored events. +*/ + +/*! \fn void QTestEventList::clear() + + Removes all events from the list. +*/ + +/*! \fn void QTestEventList::addKeyClick(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key click to the list. The event will simulate the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyClick() +*/ + +/*! \fn void QTestEventList::addKeyPress(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key press to the list. The event will press the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyPress() +*/ + +/*! \fn void QTestEventList::addKeyRelease(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key release to the list. The event will release the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyRelease() + +*/ + +/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + \internal +*/ + +/*! \fn void QTestEventList::addKeyClick(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key click to the list. The event will simulate the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyClick() + +*/ + +/*! \fn void QTestEventList::addKeyPress(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key press to the list. The event will press the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyPress() +*/ + +/*! \fn void QTestEventList::addKeyRelease(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key release to the list. The event will release the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyRelease() +*/ + +/*! \fn void QTestEventList::addKeyClicks(const QString &keys, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds new keyboard entries to the list. The event will press the \a keys with the \a modifiers and wait \a msecs milliseconds between each key. + + \sa QTest::keyClicks() +*/ + +/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + \internal +*/ + +/*! \fn void QTestEventList::addDelay(int msecs) + + Adds a \a msecs milliseconds delay. + + \sa QTest::qWait() +*/ + +/*! \fn void QTestEventList::simulate(QWidget *w) + + Simulates the events from the list one by one on the widget \a w. + For an example, please read the \l QTestEventList class documentation. +*/ + +/*! \fn void QTestEventList::addMousePress(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse press to the list. The event will press the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ +/*! \fn void QTestEventList::addMouseRelease(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse release to the list. The event will release the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mouseRelease() +*/ +/*! \fn void QTestEventList::addMouseClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse click to the list. The event will click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mouseClick() +*/ +/*! \fn void QTestEventList::addMouseDClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a double mouse click to the list. The event will double click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ +/*! \fn void QTestEventList::addMouseMove(QPoint pos = QPoint(), int delay=-1) + + Adds a mouse move to the list. The event will move the mouse to the position \a pos. If a \a delay (in milliseconds) is set, the test will wait after moving the mouse. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ + diff --git a/doc/src/classes/qvarlengtharray.qdoc b/doc/src/classes/qvarlengtharray.qdoc new file mode 100644 index 0000000..ac6bb6e --- /dev/null +++ b/doc/src/classes/qvarlengtharray.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QVarLengthArray + \brief The QVarLengthArray class provides a low-level variable-length array. + + \ingroup tools + \reentrant + + The C++ language doesn't support variable-length arrays on the stack. + For example, the following code won't compile: + + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 + + The alternative is to allocate the array on the heap (with + \c{new}): + + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 + + However, if myfunc() is called very frequently from the + application's inner loop, heap allocation can be a major source + of slowdown. + + QVarLengthArray is an attempt to work around this gap in the C++ + language. It allocates a certain number of elements on the stack, + and if you resize the array to a larger size, it automatically + uses the heap instead. Stack allocation has the advantage that + it is much faster than heap allocation. + + Example: + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 + + In the example above, QVarLengthArray will preallocate 1024 + elements on the stack and use them unless \c{n + 1} is greater + than 1024. If you omit the second template argument, + QVarLengthArray's default of 256 is used. + + QVarLengthArray's value type must be an \l{assignable data type}. + This covers most data types that are commonly used, but the + compiler won't let you, for example, store a QWidget as a value; + instead, store a QWidget *. + + QVarLengthArray, like QVector, provides a resizable array data + structure. The main differences between the two classes are: + + \list + \o QVarLengthArray's API is much more low-level. It provides no + iterators and lacks much of QVector's functionality. + + \o QVarLengthArray doesn't initialize the memory if the value is + a basic type. (QVector always does.) + + \o QVector uses \l{implicit sharing} as a memory optimization. + QVarLengthArray doesn't provide that feature; however, it + usually produces slightly better performance due to reduced + overhead, especially in tight loops. + \endlist + + In summary, QVarLengthArray is a low-level optimization class + that only makes sense in very specific cases. It is used a few + places inside Qt and was added to Qt's public API for the + convenience of advanced users. + + \sa QVector, QList, QLinkedList +*/ + +/*! \fn QVarLengthArray::QVarLengthArray(int size) + + Constructs an array with an initial size of \a size elements. + + If the value type is a primitive type (e.g., char, int, float) or + a pointer type (e.g., QWidget *), the elements are not + initialized. For other types, the elements are initialized with a + \l{default-constructed value}. +*/ + +/*! \fn QVarLengthArray::~QVarLengthArray() + + Destroys the array. +*/ + +/*! \fn int QVarLengthArray::size() const + + Returns the number of elements in the array. + + \sa isEmpty(), resize() +*/ + +/*! \fn int QVarLengthArray::count() const + + Same as size(). + + \sa isEmpty(), resize() +*/ + +/*! \fn bool QVarLengthArray::isEmpty() const + + Returns true if the array has size 0; otherwise returns false. + + \sa size(), resize() +*/ + +/*! \fn void QVarLengthArray::clear() + + Removes all the elements from the array. + + Same as resize(0). +*/ + +/*! \fn void QVarLengthArray::resize(int size) + + Sets the size of the array to \a size. If \a size is greater than + the current size, elements are added to the end. If \a size is + less than the current size, elements are removed from the end. + + If the value type is a primitive type (e.g., char, int, float) or + a pointer type (e.g., QWidget *), new elements are not + initialized. For other types, the elements are initialized with a + \l{default-constructed value}. + + \sa size() +*/ + +/*! \fn int QVarLengthArray::capacity() const + + Returns the maximum number of elements that can be stored in the + array without forcing a reallocation. + + The sole purpose of this function is to provide a means of fine + tuning QVarLengthArray's memory usage. In general, you will rarely ever + need to call this function. If you want to know how many items are + in the array, call size(). + + \sa reserve() +*/ + +/*! \fn void QVarLengthArray::reserve(int size) + + Attempts to allocate memory for at least \a size elements. If you + know in advance how large the array can get, you can call this + function and if you call resize() often, you are likely to get + better performance. If \a size is an underestimate, the worst + that will happen is that the QVarLengthArray will be a bit + slower. + + The sole purpose of this function is to provide a means of fine + tuning QVarLengthArray's memory usage. In general, you will + rarely ever need to call this function. If you want to change the + size of the array, call resize(). + + \sa capacity() +*/ + +/*! \fn T &QVarLengthArray::operator[](int i) + + Returns a reference to the item at index position \a i. + + \a i must be a valid index position in the array (i.e., 0 <= \a i + < size()). + + \sa data() +*/ + +/*! \fn const T &QVarLengthArray::operator[](int i) const + + \overload +*/ + + +/*! + \fn void QVarLengthArray::append(const T &t) + + Appends item \a t to the array, extending the array if necessary. + + \sa removeLast() +*/ + + +/*! + \fn inline void QVarLengthArray::removeLast() + \since 4.5 + + Decreases the size of the array by one. The allocated size is not changed. + + \sa append() +*/ + +/*! + \fn void QVarLengthArray::append(const T *buf, int size) + + Appends \a size amount of items referenced by \a buf to this array. +*/ + + +/*! \fn T *QVarLengthArray::data() + + Returns a pointer to the data stored in the array. The pointer can + be used to access and modify the items in the array. + + Example: + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 + + The pointer remains valid as long as the array isn't reallocated. + + This function is mostly useful to pass an array to a function + that accepts a plain C++ array. + + \sa constData(), operator[]() +*/ + +/*! \fn const T *QVarLengthArray::data() const + + \overload +*/ + +/*! \fn const T *QVarLengthArray::constData() const + + Returns a const pointer to the data stored in the array. The + pointer can be used to access the items in the array. The + pointer remains valid as long as the array isn't reallocated. + + This function is mostly useful to pass an array to a function + that accepts a plain C++ array. + + \sa data(), operator[]() +*/ + +/*! \fn QVarLengthArray &QVarLengthArray::operator=(const QVarLengthArray &other) + Assigns \a other to this array and returns a reference to this array. + */ + +/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray &other) + Constructs a copy of \a other. + */ + diff --git a/doc/src/classes/qwaitcondition.qdoc b/doc/src/classes/qwaitcondition.qdoc new file mode 100644 index 0000000..ae94e35 --- /dev/null +++ b/doc/src/classes/qwaitcondition.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QWaitCondition + \brief The QWaitCondition class provides a condition variable for + synchronizing threads. + + \threadsafe + + \ingroup thread + \ingroup environment + + QWaitCondition allows a thread to tell other threads that some + sort of condition has been met. One or many threads can block + waiting for a QWaitCondition to set a condition with wakeOne() or + wakeAll(). Use wakeOne() to wake one randomly selected condition or + wakeAll() to wake them all. + + For example, let's suppose that we have three tasks that should + be performed whenever the user presses a key. Each task could be + split into a thread, each of which would have a + \l{QThread::run()}{run()} body like this: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0 + + Here, the \c keyPressed variable is a global variable of type + QWaitCondition. + + A fourth thread would read key presses and wake the other three + threads up every time it receives one, like this: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1 + + The order in which the three threads are woken up is undefined. + Also, if some of the threads are still in \c do_something() when + the key is pressed, they won't be woken up (since they're not + waiting on the condition variable) and so the task will not be + performed for that key press. This issue can be solved using a + counter and a QMutex to guard it. For example, here's the new + code for the worker threads: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2 + + Here's the code for the fourth thread: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3 + + The mutex is necessary because the results of two threads + attempting to change the value of the same variable + simultaneously are unpredictable. + + Wait conditions are a powerful thread synchronization primitive. + The \l{threads/waitconditions}{Wait Conditions} example shows how + to use QWaitCondition as an alternative to QSemaphore for + controlling access to a circular buffer shared by a producer + thread and a consumer thread. + + \sa QMutex, QSemaphore, QThread, {Wait Conditions Example} +*/ + +/*! + \fn QWaitCondition::QWaitCondition() + + Constructs a new wait condition object. +*/ + +/*! + \fn QWaitCondition::~QWaitCondition() + + Destroys the wait condition object. +*/ + +/*! + \fn void QWaitCondition::wakeOne() + + Wakes one thread waiting on the wait condition. The thread that + is woken up depends on the operating system's scheduling + policies, and cannot be controlled or predicted. + + If you want to wake up a specific thread, the solution is + typically to use different wait conditions and have different + threads wait on different conditions. + + \sa wakeAll() +*/ + +/*! + \fn void QWaitCondition::wakeAll() + + Wakes all threads waiting on the wait condition. The order in + which the threads are woken up depends on the operating system's + scheduling policies and cannot be controlled or predicted. + + \sa wakeOne() +*/ + +/*! + \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time) + + Releases the locked \a mutex and waits on the wait condition. The + \a mutex must be initially locked by the calling thread. If \a + mutex is not in a locked state, this function returns + immediately. If \a mutex is a recursive mutex, this function + returns immediately. The \a mutex will be unlocked, and the + calling thread will block until either of these conditions is met: + + \list + \o Another thread signals it using wakeOne() or wakeAll(). This + function will return true in this case. + \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX + (the default), then the wait will never timeout (the event + must be signalled). This function will return false if the + wait timed out. + \endlist + + The mutex will be returned to the same locked state. This + function is provided to allow the atomic transition from the + locked state to the wait state. + + \sa wakeOne(), wakeAll() +*/ + +/*! + \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time) + \since 4.4 + + Releases the locked \a readWriteLock and waits on the wait + condition. The \a readWriteLock must be initially locked by the + calling thread. If \a readWriteLock is not in a locked state, this + function returns immediately. The \a readWriteLock must not be + locked recursively, otherwise this function will not release the + lock properly. The \a readWriteLock will be unlocked, and the + calling thread will block until either of these conditions is met: + + \list + \o Another thread signals it using wakeOne() or wakeAll(). This + function will return true in this case. + \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX + (the default), then the wait will never timeout (the event + must be signalled). This function will return false if the + wait timed out. + \endlist + + The \a readWriteLock will be returned to the same locked + state. This function is provided to allow the atomic transition + from the locked state to the wait state. + + \sa wakeOne(), wakeAll() +*/ diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc deleted file mode 100644 index 09274bf..0000000 --- a/doc/src/phonon-api.qdoc +++ /dev/null @@ -1,5023 +0,0 @@ -/* - This file is part of the KDE project - Copyright (C) 2005-2007 Matthias Kretz - Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). - Contact: Nokia Corporation (qt-info@nokia.com) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License version 2 as published by the Free Software Foundation. - - This library 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 - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ - - -/*! - \enum Phonon::DiscType - Enum to identify the media discs supported by MediaObject. - - \value NoDisc - No disc was selected. This is only useful as a return value from - MediaSource::diskType(). - \value Cd Identifies Audio CDs. - \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). - \value Vcd Identifies Video CDs. - - \sa MediaSource, MediaObject -*/ - -/*! - \enum Phonon::MetaData - - Provided as keys for Phonon::MediaObject::metaData(). The enum - values matches strings defined in the Ogg Vorbis specification - - \value ArtistMetaData - \value AlbumMetaData - \value TitleMetaData - \value DateMetaData - \value GenreMetaData - \value TracknumberMetaData - \value DescriptionMetaData - \value MusicBrainzDiscIdMetaData -*/ - -/*! - \enum Phonon::State - \since 4.4 - - The state enum describes the different states a media object can - take. Several functions of \l{Phonon::}{MediaObject} are - asynchronous, so even if a you have requested a state change - through a function call, e.g., through - \l{Phonon::MediaObject::}{play()}, you cannot be sure that the - change has taken place before you receive the - \l{Phonon::MediaObject::}{stateChanged()} signal. - - A media object can at any time change into any state, regardless - of the state it previously had. \omit In the - \l{Phonon::}{MediaObject} class description explains the typical - state changes in the life of a media object. \endomit - - \value LoadingState - After construction it might take a while before the media object - is ready to \l{Phonon::MediaObject::}{play()}. This state is - commonly used by backends to initialize the \l{Phonon - Overview}{media graph} and loading the source. When - the object leaves the loading state, it will enter the - StoppedState unless an error occurred or another state is - requested through a function call, e.g., - \l{Phonon::}{MediaObject::play()}. - - \value StoppedState - In the stopped state, the media object is ready to play its - current media source. The current - \l{MediaObject::seek()}{position} in the media stream is then 0. - - \value PlayingState - The media object is playing back its media source. - - \value BufferingState - The Player is waiting for data to be able to start or continue - playing. This state is commonly used to wait for media data over a - network connection. - - \value PausedState - The media player has currently paused its playback, i.e., it - stops playing but keeps the current playback position in the - stream. - - \value ErrorState - When a media object enters the error state a problem with the - playback has occurred. The possible errors are grouped into - two categories by Phonon::ErrorType, and the type can be - queried through \l{Phonon::MediaObject::}{errorType()}. A - \l{Phonon::}{FatalError} implies that the playback - cannot continue, but one can still try with a new media - source. With a \l{Phonon::}{NormalError} it might - be possible to continue playback, and a media object may - therefore change state from the ErrorState. - - \sa MediaObject -*/ - -/*! - \enum Phonon::Category - - Sets the category your program should be listed in in the mixer. - - \value NoCategory - Will make use of the default device. - \value NotificationCategory - If the sounds produced are notifications (ping, beep and such) you - should use this category. - \value MusicCategory - If your application is a music player (like a jukebox or media player - playing an audio file). - \value VideoCategory - If the sound is the audio channel of a video. - \value CommunicationCategory - If your applications produces sounds from communication with somebody - else (VoIP, voice chat). - \value GameCategory - Sound produced by a computer game should go into this category. - \value AccessibilityCategory - Sounds produced for accessibility (e.g., Text-To-Speech) - \omitvalue LastCategory - Holds the largest value of categories. - \omitvalue AccessibilityCategory - - A Jukebox will set this to Music, a VoIP program to Communication, a - DVD player to video, and so on. - - \note These categories can also become useful for an application that - controls the volumes automatically, like turning down the music when a call - comes in, or turning down the notifications when the media player knows - it's playing classical music. -*/ - -/*! - \enum Phonon::ErrorType - - This enum describes the severity when an error has occurred during - playback. - - After a media object has entered the \l{Phonon::}{ErrorState}, one - can query the type of error from - \l{Phonon::}{MediaObject::errorType()}. Note that you should query - the error when receiving the - \l{Phonon::}{MediaObject::stateChanged()} signal, because the - error type will be lost if the media object leaves the error - state. - - \value NoError No error. MediaObject::errorType() returns this if - MediaObject::state() != Phonon::ErrorState. - - \value NormalError An error has occurred with the playback of the current - source. It might be possible to continue playback, for instance, if only the - audio stream in a video cannot be played back. The media object will then - leave the error state again. - - \value FatalError. Something important does not work. Your program cannot continue - the playback of the current source, but it might be possible to try another. - - \sa MediaObject::errorType() -*/ - -/*! - \fn QString Phonon::categoryToString(Category c) - - Returns a (translated) string to show to the user identifying the given - Category (\a c). -*/ - -/*! - \enum Phonon::ObjectDescriptionType - \relates Phonon::ObjectDescription - - This enum defines the type of information that is contained in a - \l{Phonon::}{ObjectDescription} object. - - \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). - This can be soundcards (with different drivers), - sound servers, or other virtual outputs like playback on a different - computer on the network. - - \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). - \omitvalue SubtitleType - \omitvalue AudioCaptureDeviceType - \omitvalue AudioChannelType -*/ - -/*! - \typedef Phonon::AudioOutputDevice - \relates Phonon::ObjectDescription - - This typedef of \l{Phonon::}{ObjectDescription} describes an audio output - device, such as soundcards (with different drivers), sound servers, or other - virtual outputs like playback on a different computer on the network. - - \omit - For Hardware devices the backend should use libkaudiodevicelist - (AudioDevice and AudioDeviceEnumerator) which will list removable - devices even when they are unplugged and provide a unique identifier - that can make backends use the same identifiers. - \endomit - - A list of available devices is given by the backend with - Backendcapabilities::availableAudioOutputDevices() - - \snippet doc/src/snippets/phononobjectdescription.cpp 1 - -*/ - -/*! - \fn Phonon::phononVersion() - \inmodule Phonon - \since 4.5 - - Returns the Phonon version. -*/ - -/*! - \class Phonon::ObjectDescription - \inmodule Phonon - \inheaderfile Phonon/ObjectDescription - \since 4.4 - \brief The ObjectDescription class provides information about Phonon objects. - - Phonon currently uses this class to describe audio effects and - audio output devices - using the typedefs AudioOutputDevice and - EffectDescription. The type of an ObjectDescription is also - described through the \l{Phonon::}{ObjectDescriptionType} enum. - Objects of the same \l{Phonon::ObjectDescriptionType}{type} are - uniquely identified by an index(). - - The class gives a description() and a name() of the object, both - of which are strings appropriate for end users of a Phonon - application. You can also check whether the device or effect - described is \l{isValid()}{valid}. This does not guarantee that - the device or effect functions as expected, but that the - ObjectDescription describes an existing device or effect. - - Audio output devices and effect descriptions are used to select - the audio output device to be used for playback and to create - effects; we show examples of this in the snippet below. The - available descriptions can be fetched with - \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} - and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} - static functions in the Phonon::BackendCapabilities namespace - - \snippet doc/src/snippets/phononobjectdescription.cpp 0 - - Other types of ObjectDescriptions might be possible in the future, - e.g., descriptions of audio capture devices, such as microphones. - - \omit Not implemented yet. - Need a new paragraph on that some descriptions 'belong - together', such as chained audio effects. - - Some parts give the end user choices, e.g. what source to capture - audio from. These choices are described by the name and - description methods of this class and identified with the id - method. Subclasses then define additional information like which - audio and video choices belong together. \endomit - - \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription() - \brief constructs a new object description. - \internal -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash & properties) - \internal -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer &dd) - \internal -*/ - -/*! - \fn static inline ObjectDescription Phonon::ObjectDescription::fromIndex(int index) - \internal - - \omit Currently indices are not unique for all ObjectDescription types, making - the behavior of this function undefined. \endomit - - Returns a new description object that describes the - device/effect/codec/... with the given \a index. -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const - - Returns \c true if this ObjectDescription describes the same - object as \a otherDescription; otherwise, returns \c false. -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const - Returns \c false if this ObjectDescription describes the same - as \a otherDescription; otherwise, returns \c true. -*/ - -/*! - \fn inline QString Phonon::ObjectDescription::name() const - - Returns a string appropriate for a user to select between - object descriptions, e.g., from a QComboBox. - - \sa description() -*/ - -/*! - \fn inline QString Phonon::ObjectDescription::description() const - - Returns a more extensive description than the name() function. - - For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this - text should make clear which sound source is described; this is - sometimes hard to describe or understand from just the name. - - The text is appropriate to present to an end user in for example - tool tips of items, with the name()'s as text, in a QComboBox. - -*/ - -/*! - \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const - - Returns the property named \a name. A property can be used for - extended information, such as the manufacturer of a sound card. The - information will usually be given as text. - - If the property is not set an invalid QVariant is returned. - - Qt's backends do not use properties at the time of this writing. - - \sa propertyNames() -*/ - -/*! - \fn inline QList Phonon::ObjectDescription::propertyNames() const - - Properties can be used for extended information about a - ObjectDescription, e.g., a manufacturer of a sound card. The - information will usually be given text. - - This function returns all names that return valid data when - property() is called. - - Currently, Qt backends do not use properties for their object - descriptions. - - \sa property() -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::isValid() const - - Returns true if the device or effect described exists. - - An ObjectDescription that is invalid, will also have an - index() of -1. - - \sa index() -*/ - -/*! - \fn inline int Phonon::ObjectDescription::index() const - - Returns a unique identifier for this ObjectDescription. Used - internally to distinguish between the descriptions. - - Notice that the identifiers are only unique to the type of - description, e.g., \l{Phonon::}{AudioOutputDevice} or - \l{Phonon::}{EffectDescription}. -*/ - -/*! - \class Phonon::ObjectDescriptionPrivate - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::StreamInterface - \inmodule Phonon - \since 4.4 - \brief Backend interface to handle media streams (AbstractMediaStream). - \internal -*/ - -/*! - \fn virtual Phonon::StreamInterface::~StreamInterface() -*/ - -/*! - \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::endOfData() = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::needData() - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::enoughData() - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::seekStream(qint64) - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::reset() - \internal -*/ - -/*! - \fn Phonon::StreamInterface::StreamInterface() - \internal - \omit - For subclasses. - \endomit -*/ - -/*! - \class StreamInterfacePrivate - \inmodule Phonon - \internal -*/ - -/*! - \class Phonon::AbstractVideoOutput - \inmodule Phonon - \internal - \since 4.4 - \brief The AbstractVideoOutput class is the common base class for all video output classes. - - \sa VideoWidget -*/ - -/*! - \namespace Phonon::Experimental - \internal -*/ - -/*! - \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) - \internal - - Constructor that is called from derived classes. - - \param parent Standard QObject parent. -*/ - -/*! - \class Phonon::AbstractVideoOutputPrivate - \inmodule Phonon - \internal - \since 4.4 -*/ - -/*! - \class Phonon::VolumeFaderEffect - \inmodule Phonon - \internal - \since 4.4 - - This effect differs from gradually changing the output volume in that - a dedicated effect can change the volume in the smallest possible - steps while every other volume control will make more or less - noticeable steps. - - \sa AudioOutput::volume() -*/ - -/*! - \property Phonon::VolumeFaderEffect::volume - - This is the current volume of the output as voltage factor. - Setting this property changes the volume immediately. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% - - \sa volumeDecibel -*/ - -/*! - \property Phonon::VolumeFaderEffect::volumeDecibel - - This is the current volume of the output in decibel. - Setting this property changes the volume immediately. - - 0 dB means no change in volume, -6dB means an attenuation of the - voltage to 50% and an attenuation of the power to 25%, -inf dB means - silence. - - \sa volume -*/ - -/*! - \property Phonon::VolumeFaderEffect::fadeCurve - - This property holds the fade curve to be used for the fadeIn(), fadeOut() - and fadeTo() slots. - - Defaults to Fade3Decibel. - - \sa FadeCurve -*/ - -/*! - \enum Phonon::VolumeFaderEffect::FadeCurve - Determines the curve of the volume change. - - \value Fade3Decibel Crossfade curve/fast fade out. - This is the default fade curve. - \value Fade6Decibel Linear fade out. - \value Fade9Decibel Slow fade out. - \value Fade12Decibel A more extreme version of the -9dB fade. - - \bold{Notes:} - - \c Fade3Decibel is often the best fade for a crossfade, as after half - of the time the volume reached -3dB. This means that half the - possible power (which is proportional to the square of the - voltage) is reached. Summed, the maximum power of two audio - signals fading with a -3dB curve will always be equal. - - For fading in or out the -3dB curve is too abrupt in the end. - - With a -6dB fade curve, a volume of -6dB is reached after half of - the fading time. -6dB is equal to half of the voltage meaning - that the voltage multiplier changes linearly from the start - of the fade to the end. - - With the \c Fade9Decibel fade, a volume of -9dB is reached after - half of the fade time, so the fade is fast in the beginning and - slow at the end. This is a good fade for ending music. -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) - - Tells the Fader to change the volume from the current volume to 100% - in \a fadeTime milliseconds. - - Short for \c fadeTo(1.0, fadeTime). - - \param fadeTime the fade duration in milliseconds - - \sa fadeTo(), volume -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) - - Tells the Fader to change the volume from the current volume to 0% - in \a fadeTime milliseconds. - Short for \c fadeTo(0.0, fadeTime). - - \param fadeTime the fade duration in milliseconds - - \sa fadeTo -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) - - Tells the Fader to change the volume from the current value to - \a volume in \a fadeTime milliseconds. - - \sa fadeIn(), fadeOut() -*/ - -/*! - \class Phonon::VolumeFaderEffectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::VolumeFaderInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() - \internal -*/ - -/*! - \fn virtual float Phonon::VolumeFaderInterface::volume() const - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) - \internal -*/ - -/*! - \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) - \internal -*/ - -/*! - \class Phonon::AbstractMediaStream - \inmodule Phonon - \internal - \since 4.4 - \brief The AbstractMediaStream class is the base class for custom media data streams. - \inheaderfile Phonon/AbstractMediaStream - - This class is subclassed to provide custom data streams for - \l{Phonon::}{MediaSource}s. - - The \l{Phonon::}{MediaSource} knows how to handle the most common - media sources, such as files and CD. If you need to fetch - multimedia from other sources, you can reimplement this class, - which can be used by a \l{Phonon::}{MediaSource}. - - When a backend needs more data from the stream, needData() will be - called. You must then use writeData() to write the data to the - backend. You can either write one time and wait for a new - needData() call, or continue to write data until you receive an - enoughData() call. When the stream is at its end, call endOfData() - instead of writeData(). - - Before the custom stream is passed to a \l{Phonon::}{MediaSource}, - setStreamSize() needs to be called, and also setStreamSeekable() - (if the stream is seekable). A good place to do this work is in - the constructor. A seekable stream must also reimplement - seekStream(). - - We show two examples. The first writes data repeatedly until it - receives the enoughData() call, while the second only writes once - and waits for a new needData() call. - - Example where data is written repeatedly. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 - - Example where data is written once: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 - - \sa Phonon::MediaSource, Phonon::MediaObject - -*/ - -/*! - \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) - \internal - - Constructs an AbstractMediaStream object with the given \a parent. - -*/ - -/*! - \fn qint64 Phonon::AbstractMediaStream::streamSize() const - - Returns the stream size that was set with setStreamSize(). - - A negative value means that the length of the stream cannot be known. - - Defaults to 0. - - \sa setStreamSize() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) - - Sets the \a size of the stream in number of bytes. - - A negative value means that the length of the stream cannot be known. - - Defaults to 0. - - This function has to be called. A backend will not call needData() - until the stream size is set. - - \sa streamSize() - -*/ - -/*! - \fn bool Phonon::AbstractMediaStream::streamSeekable() const - - Returns whether your data stream is set as seekable. - - Defaults to \c false. - - \sa setStreamSeekable() - -*/ - -/*! - \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) - - Sets whether your data stream is seekable. \a s should be true if - the stream is seekable; otherwise false. - - Defaults to \c false. - - If you set this to \c true you have to implement the seekStream() - function. - - \sa streamSeekable() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) - - Sends the media \a data to the backend for decoding. - - Use this function to send data to the backend after needData() has - been called. - - If your stream is a push stream, data should be written until the - enoughData() function is called. For a pull stream, write data - once before the call to needData() function returns. - - If the data is depleted, call endOfData() instead of writeData(). - - \warning Don't call this function before the first needData() is emitted. - - \sa needData(), endOfData() - -*/ - -/*! - \fn void Phonon::AbstractMediaStream::endOfData() - - Tells the backend that the media data stream is at its end. - - \warning Don't call this function before the first needData() is emitted. - - \sa writeData(), needData() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) - - If an I/O error occurs you should call this function to make - MediaObject go into ErrorState. \c errorType classifies the error, - while \a errorString is a textual description of the error suitable - for users of Phonon applications. - - \sa MediaObject::errorType(), MediaObject::errorString() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::reset() = 0 - - Reimplement this function to reset the stream. Subsequent calls to writeData should start - from the first position of the data unless a seek is requested. - - The function is necessary for the case where a non-seekable MediaStream is - played more than once. For a seekable stream the implementation can simply call - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 - - \sa writeData(), needData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::needData() = 0 - - Reimplement this function to be notified when the backend needs data. - - When this function is called you should write data to the backend - (See writeData()). - - \sa writeData(), endOfData(), enoughData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::enoughData() - - If your stream is a push stream, reimplement this function to be - notified when the backend has enough data and your stream object - may take a break. - - This method is important for pushing data to the backend in order - to not fill the backend buffer unnecessarily. - - \sa needData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) - - Reimplement this function if your stream is seekable. - - When this function is called the next call to writeData has to be at the - requested \a offset. - - \warning Do not call the parent implementation. - - \sa setStreamSeekable(), streamSeekable(), needData() -*/ - -/*! - \class Phonon::BackendInterface - \inmodule Phonon - \since 4.4 - \brief Main Backend class interface - \internal - - This interface defines the main factory of the backend. The createObject() function creates all the - objects needed by the frontend. - - The objectDescriptionIndexes and objectDescriptionProperties functions return information about - available devices, effects and codecs. - - An implementation could look like this: - \snippet snippets/phonon/samplebackend/main.cpp snippet - -*/ - -/*! - \fn virtual Phonon::BackendInterface::~BackendInterface() - \internal - - Silence gcc's warning. -*/ - -/*! - \enum Phonon::BackendInterface::Class - \internal - - Classes that the createObject() function has to handle. - - \value MediaObjectClass Request to return a \c MediaObject object. - \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect - object. - \value AudioOutputClass Request to return an \c AudioOutput object. - \value AudioDataOutputClass Request to return an \c AudioDataOutput object. - \value VisualizationClass Request to return a \c Visualization object. - \value VideoDataOutputClass Request to return a \c VideoDataOutput object. - \value EffectClass Request to return a \c Effect object. - Takes an additional int that specifies the effect ID. - \value VideoWidgetClass Request to return a \c VideoWidget object. -*/ - -/*! - \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList &args = QList()) = 0 - \internal - - Returns a new instance of the requested class. - - \param c The requested class. - \param parent The parent object. - \param args Additional arguments (documented in Class). -*/ - - -/*! - \fn virtual QList Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 - \internal - - Returns the unique identifiers for the devices/effects/codecs of the given \a type. - - \param type see ObjectDescriptionType -*/ - -/*! - \fn virtual QHash Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 - \internal - - Given a unique identifier that was returned from objectDescriptionIndexes this function - returns a hash mapping property names to values. - - The property "name" must always be present. All other properties are optional. - - \table - \header \o Property \o Description - \row \o name \o The name of the device/effect/codec/... - \row \o description \o A text explaining what this device/effect/codec/... is/can do - \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this - device/effect/codec/... - \row \o available \o A bool telling whether the device is present or unplugged. - \endtable - - \param type see ObjectDescriptionType - \param index The unique identifier that is returned from objectDescriptionIndexes -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet) = 0; - \internal - - When this function is called the nodes given in the parameter list should - not lose any signal data when connections are changed. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 - \internal - - Defines a signal connection between the two given nodes. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 - \internal - - Cuts a signal connection between the two given nodes. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet) = 0 - \internal - - When this function is called the nodes given in the parameter list may lose - signal data when a port is not connected. -*/ - -/*! - \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 - \internal - - Returns all available MIME types. -*/ - -/*! - \class Phonon::MediaSource - \inmodule Phonon - \inheaderfile Phonon/MediaSource - \since 4.4 - \brief The MediaSource class provides multimedia data for media objects. - - The MediaSource class manages a source of multimedia content, such - as a music or video file, of which data is given to a - \l{Phonon::}{MediaObject}. - - The media source knows how fetch its data from several sources, - e.g., from files, a QIODevice, or a CD. The possible source types - are described by the \l{MediaSource::}{Type} enum. The type of the - source is set by the media source itself, and is dependent on the - constructor used to create it. Note that it is possible to provide - data from any source by implementing a QIODevice. - - The class has several functions to acquire information about the - source it manages, e.g., fileName() and url(). The return from - these functions are dependent on the type() of the media source. - - Normally, a programmer does not need to be concerned with media - sources. It's constructors are implicit, so one can, for instance, - send an URL or filename directly to the constructors of the - \l{Phonon::}{MediaObject}. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 - - A MediaSource object cannot be reused for another multimedia - source. It is possible to play the same source again, and also - stop and start a non-seekable media source, such as a radio - stream, with the same MediaSource object. - - \section1 Qt Backends - - Currently, Qt's backends support files in local and remote - locations. Support for other sources, such as CD/DVD, are planned - for the future. - - \sa MediaObject, {Phonon Module} -*/ - -/*! - \enum Phonon::MediaSource::Type - - Identifies the type of media described by the MediaSource object. - - \value Invalid The MediaSource object does not describe any valid source. - \value LocalFile The MediaSource object describes a local file. - \value Url The MediaSource object describes an URL, which can be either a - local file or a file on the network. - \value Disc The MediaSource object describes a disc, e.g., a CD. - \value Stream The MediaSource object describes a data stream. - This is the type used for \l{QIODevice}s. Note - that a stream opened with a QUrl, will still be of the Url type. - \value Empty The media source doesn't have a source. - - \sa MediaSource::type() -*/ - -/*! - \fn Phonon::MediaSource::MediaSource() - \internal - - Creates an invalid MediaSource object. - - \sa Invalid -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const QString &fileName) - - Creates a MediaSource object for the file specified by \a - fileName. You can also use this constructor with \l{The Qt - Resource System}{Qt resources} - - \omit - \param fileName file name of a local media file or a Qt resource that was compiled in. - \endomit -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const QUrl &url) - - Creates a MediaSource object for a the URL specified by \a url. - - If the multimedia content you would like to play back is on a - remote network location, you should use this constructor; though, - it also possible to specify an URL to a local file. - - \sa QUrl -*/ - - -/*! - \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) - - Creates a MediaSource object for the type of disc specified by \a discType in the named - device referred to by \a deviceName. - - \note \a deviceName is a platform dependent device name. It can be useful to specify this - if the computer has more than one CD drive. On KDE, it is recommended to use the Solid - hardware discovery framework to retrieve the device name in a portable way. -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) - \internal - Creates a MediaSource object for a data stream. - - Your application can provide the media data by subclassing AbstractMediaStream and - passing a pointer to that object. Phonon will never delete the \a stream. - - \param stream The AbstractMediaStream subclass to provide the media data. - - \sa setAutoDelete -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) - - Creates a MediaSource object for the QIODevice specified by \a ioDevice. - - This constructor can be very handy in the combination of - QByteArray and QBuffer. - - If you need to fetch multimedia data from a source that is not - supported by MediaSource, you should subclass QIODevice and use - this MediaSource constructor. It is important that you reimplement - QIODevice::isSequential(), as it is used by MediaSource to - determine if the media source is seekable. - - \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened - MediaSource will open it as QIODevice::ReadOnly. - - \note Sequential devices can also be used, but MediaObject::isSeekable() will - return false as a result. - - \warning On Windows, we only support \l{QIODevice}s containing the - \c avi, \c mp3, or \c mpg formats. Use the constructor that takes - a file name to open files (the Qt backend does not use a QFile - internally). - - \sa setAutoDelete() -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) - \internal -*/ - -/*! - \fn Phonon::MediaSource::~MediaSource() - - Destroys the MediaSource object. You should never delete a - MediaSource yourself, the MediaObject will handle this. - -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const MediaSource &other) - - Constructs a copy of the \a other media source. - - This constructor is fast thanks to explicit sharing. -*/ - -/*! - \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) - - Assigns the \a other media source to this media source and returns a - reference to it. - - This operation is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const - - Returns true if this media source is equal to the \a other media source; - otherwise returns false. -*/ - -/*! - \fn void Phonon::MediaSource::setAutoDelete(bool enable) - - If \a enable is true, the media source will take ownership of the - object passed in the \l{Phonon::}{MediaSource}'s constructor - object that was passed in the constructor; otherwise, the - programmer is responsible for deletion of this object. - - This setting is false by default. If you enable it, you should - only access the stream or device as long as you keep the media - source object around. As long as you keep the media source - wrapping the stream or device, the object will not get deleted. - - \sa autoDelete() -*/ - -/*! - \fn bool Phonon::MediaSource::autoDelete() const - - Returns the setting of the auto-delete option. The default is - false. - - \sa setAutoDelete() -*/ - -/*! - \fn Type Phonon::MediaSource::type() const - - Returns the type of the MediaSource (depends on the constructor - that was used). - - \sa Type -*/ - -/*! - \fn QString Phonon::MediaSource::fileName() const - - Returns the file name of the MediaSource if type() == - LocalFile; otherwise, returns QString(). - - \sa type() -*/ - -/*! - \fn QUrl Phonon::MediaSource::url() const - Returns the URL of the MediaSource if type() == URL or type() == LocalFile; - otherwise returns QUrl(). - - \sa type() -*/ - -/*! - \fn Phonon::DiscType Phonon::MediaSource::discType() const - Returns the disc type of the MediaSource if type() == Disc; otherwise - returns NoDisc. - - \sa type() -*/ - -/*! - \fn QString Phonon::MediaSource::deviceName() const - - Returns the device name of the MediaSource if type() == Disc; otherwise - returns QString(). - - \sa type() -*/ - -/*! - \fn AbstractMediaStream *Phonon::MediaSource::stream() const - \internal - Returns the media stream of the MediaSource if type() == Stream; otherwise - returns 0. - QIODevices are handled as streams, too. -*/ - -/*! - \class Phonon::MediaSourcePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::SeekSlider - \inmodule Phonon - \inheaderfile Phonon/SeekSlider - \since 4.4 - \brief The SeekSlider class provides a slider for seeking to positions in media streams. - - The SeekSlider connects to a \l{Phonon::}{MediaObject}, and - controls the seek position in the object's media stream. - - The slider will connect to the necessary signals to keep track of - the sliders maximum, minimum, and current values. It will also - disable itself for non-seekable streams, and update the media - object when the current value of the slider changes. - - Here follows a typical example of SeekSlider usage: - - \snippet doc/src/snippets/seekslider.cpp 0 - - \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} - -*/ - -/*! - \property Phonon::SeekSlider::iconVisible - \brief whether the icon next to the slider is visible - - By default the icon is visible if the platform provides an icon; else - it's hidden. - -*/ - -/*! - \property Phonon::SeekSlider::tracking - \brief whether slider tracking is enabled - - If tracking is enabled (the default), the media seeks - while the slider is being dragged. If tracking is - disabled, the media seeks only when the user - releases the slider. -*/ - -/*! - \property Phonon::SeekSlider::pageStep - \brief the page step interval - - The larger of two natural steps that a slider provides and - typically corresponds to the user pressing PageUp or PageDown. - - Defaults to 5 seconds. -*/ - -/*! - \property Phonon::SeekSlider::singleStep - \brief the single step interval - - The smaller of two natural steps that a slider provides and - typically corresponds to the user pressing an arrow key. - - Defaults to 0.5 seconds. -*/ - -/*! - \property Phonon::SeekSlider::orientation - \brief the orientation of the slider - - The orientation must be Qt::Vertical or Qt::Horizontal (the default). -*/ - -/*! - \property Phonon::SeekSlider::iconSize - \brief the icon size used for the mute button/icon. - - The default size is defined by the GUI style. -*/ - -/*! - \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) - - Constructs a seek slider widget with the given \a parent. -*/ - -/*! - \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) - - Constructs a seek slider widget for the specified \a media with the - given \a parent. -*/ - -/*! - \fn Phonon::SeekSlider::~SeekSlider() - Destroys the seek slider. -*/ - -/*! - \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const - - Return the media object this SeekSlider controls. -*/ - -/*! - \class Phonon::SeekSliderPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) - - Sets the media object to be controlled by this slider to the \a media specified. -*/ - -/*! - \class Phonon::VideoPlayer - \inmodule Phonon - \inheaderfile Phonon/VideoPlayer - \since 4.4 - \brief The VideoPlayer widget is used to perform playback of video. - - With VideoPlayer you can get results quickly and easily. You can - do the standard playback tasks like play(), pause(), and stop(), - but also set a playback volume and seek - if the media and backend - supports seeking. - - VideoPlayer is provided for convenience and removes the need to - create a media graph with a \l{Phonon::}{MediaObject}, - \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If - you need functionality not supported by the player, you can build - this \l{Building Graphs}{graph} yourself. - - Keep in mind that when the VideoPlayer instance is deleted the - playback will stop. - - Note also that most of the functions in this class are - asynchronous. For instance, a media source may not play - immediately after you call the play() function. - - A play and forget code example: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 - - \sa {Phonon Module}, MediaObject -*/ - -/*! - \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) - - Constructs a new video widget with a \a parent using - Phonon::VideoCategory as its category. - - \param parent The QObject parent. -*/ - -/*! - \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) - - Constructs a new VideoPlayer instance with the specified \a - parent. - - \a category is the category used for the audio output device. -*/ - -/*! - \fn Phonon::VideoPlayer::~VideoPlayer() - - On destruction the playback is stopped, also the audio output is - removed so that the desktop mixer will not show the application - anymore. If you need a persistent audio output don't use - VideoPlayer but MediaObject, VideoPath and VideoOutput. -*/ - -/*! - \fn qint64 Phonon::VideoPlayer::totalTime() const - - Get the total time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn qint64 Phonon::VideoPlayer::currentTime() const - - Get the current time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn float Phonon::VideoPlayer::volume() const - - This is the current volume of the output as voltage factor. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% -*/ - -/*! - \fn bool Phonon::VideoPlayer::isPlaying() const - - Returns true if it is currently playing; otherwise returns false if it - is currently stopped or paused -*/ - -/*! - \fn bool Phonon::VideoPlayer::isPaused() const - - Returns true if it is currently paused; otherwise returns false if it - is currently playing or stopped. -*/ - -/*! - \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) - - Starts pre-loading the media data from the specified \a source and - filling audio buffers in the backend. - - When there's already a media playing (or paused) it will be stopped - (the finished signal will not be emitted). - - \sa MediaObject::setCurrentSource() -*/ - -/*! - \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) - - Plays the media from the given \a source. Starts playback as fast as - possible. - This can take a considerable time depending on the URL and the - backend. - - If you need low latency between calling play() and the sound actually - starting to play on your output device you need to use MediaObject - and be able to set the URL before calling play(). Note that - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 - doesn't make a difference: the application should be idle between the - load and play calls so that the backend can start preloading the - media and fill audio buffers. -*/ - -/*! - \fn void Phonon::VideoPlayer::play() - - Continues playback of paused media. Restarts playback of a stopped - (or newly loaded) media. - - \sa MediaObject::play(), play() -*/ - -/*! - \fn void Phonon::VideoPlayer::pause() - - Pauses the playback. - - \sa MediaObject::pause() -*/ - -/*! - \fn void Phonon::VideoPlayer::stop() - - Stops the playback. - - \sa MediaObject::stop() -*/ - -/*! - \fn void Phonon::VideoPlayer::seek(qint64 ms) - - Seeks to the requested time. Note that the backend is free to - ignore the seek request if the media source isn't seekable; you - can check this by asking the media object of the VideoPlayer. - - \snippet doc/src/snippets/videomedia.cpp 0 - - The \a ms parameter is the time in milliseconds from the start of - the media. - - The call is asynchronous, so currentTime() can still be the old - value right after this method was called. If all you need is a - slider that shows the current position and allows the user to - seek, use the class SeekSlider. - - \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() -*/ - -/*! - \fn void Phonon::VideoPlayer::setVolume(float volume) - - Sets the \a volume of the output as voltage factor. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% -*/ - -/*! - \fn MediaObject *Phonon::VideoPlayer::mediaObject() const - - Returns the media object being used by the player. - - The media object can be accessed directly instead of using the - \l{VideoPlayer}s convenience functions, e.g., play() and stop(). - It is also possible to give the object to other Phonon widgets, - e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. - - \sa Phonon::SeekSlider, Phonon::MediaObject -*/ - -/*! - \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const - - Returns the audio output object being used by the player. - -*/ - -/*! - \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const - - Returns the video widget being used by the player. -*/ - -/*! - \fn void Phonon::VideoPlayer::finished() - - This signal is emitted when the playback finished. - -*/ - -/*! - \class Phonon::VideoWidgetPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaObject - \inmodule Phonon - \inheaderfile Phonon/MediaObject - \since 4.4 - \brief The MediaObject class provides an interface for media playback. - - - The media object manages a \l{Phonon::}{MediaSource}, which - supplies the media object with multimedia content, e.g., from a - file. A playback in Phonon is always started by calling the - \l{Phonon::MediaObject::}{play()} function. - - The state of play (play, pause, stop, seek) is controlled by the - media object, and you can also query the current - \l{Phonon::MediaObject::}{state()}. It keeps track of the playback - position in the media stream, and emits the - \l{Phonon::MediaObject::}{tick()} signal when the current position - in the stream changes. - - Notice that most functions of this class are asynchronous, so you - cannot rely on that a state is entered after a function call - before you receive the \l{Phonon::MediaObject::}{stateChanged()} - signal. The description of the \l{Phonon::}{State} enum gives a - description of the different states. - - Before play() is called, the media object should be connected to - \l{Sinks}{output nodes}, which outputs the media to the - underlying hardware. The output nodes required are dependent on - the contents of the multimedia file that is played back. Phonon - has currently two output nodes: the \l{Phonon::}{AudioOutput} for - audio content and \l{Phonon::}{VideoWidget} for video content. If - a \l{Phonon::}{MediaSource} contains both audio and video, both - nodes need to be connected to the media object. - - \snippet snippets/phonon.cpp 4 - \snippet snippets/phonon.cpp 5 - - The media object can queue sources for playback. When it has - finished to play one source, it will start playing the next in the - queue; the new source is then removed from the queue. The - queue can be altered at any time. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 - - You can also make use of the - \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is - guaranteed to be emitted in time for altering the queue. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 - - When playback is finishing, i.e., when a media source has been - played to the end and the queue is empty, several signals are - emitted. First, the media object will emit aboutToFinish() - - shortly before the playback has finished - and then finished(). - The stateChanged() signal will also be emitted with - \l{Phonon::}{PausedState}, which is the state the media object - takes when the playback is finished. If you wish to enter another - state, you can connect a slot to finished() and set a new state - there. - - The media object resolves the meta information, such as title, - artist, and album. The meta data is not resolved immediately after - a new source is provided, but will be resolved before the object - leaves the \l{Phonon::}{LoadingState}. The data is queried by - string keys - which should follow the Ogg Vorbis specification - \l http://xiph.org/vorbis/doc/v-comment.html - or by using the - \l{Phonon::}{MetaData} enum. The data available will depend on the - type and content of the individual media files. metaDataChanged() - will be emitted when the media object has resolved new meta data. - - Errors encountered during playback and loading of media sources - are reported by emitting a state changed signal with - \l{Phonon::}{ErrorState}. The severity of the error can be queried - by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, - it might be possible to continue the playback, for instance, if - only audio playback fails for a media source which also has video. - A \l{Phonon::}{FatalError} indicates that Phonon cannot continue - playback of the current source, but it is possible to try with a - different one. A user readable error message is given by - errorString(). - - \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, - {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, - Phonon::createPlayer(), {Phonon Module} - -*/ - -/*! - \property Phonon::MediaObject::transitionTime - \brief Defines the time between playback of two media sources - in the media queue. - - A positive transition time defines a gap of silence between queued - media sources. - - A transition time of 0 ms requests gapless playback (i.e., the - next source in the media queue starts immediately after the - playback of the current source finishes). - - A negative transition time defines a crossfade between the queued - media sources. - - Defaults to 0 (gapless playback). - - \warning This feature might not work reliably with every - backend. -*/ - -/*! - \property Phonon::MediaObject::prefinishMark - \brief the time when the prefinishMarkReached signal is emitted before playback ends. - - This property specifies the time in milliseconds the - prefinishMarkReached() signal is emitted before the playback - finishes. A value of \c 0 disables the signal. The signal is only - emitted for the last source in the \l{queue()}{media queue}. - - Defaults to \c 0 (disabled). - - \warning For some media data the total time cannot be determined - accurately, therefore the accuracy of the prefinishMarkReached signal - can be bad sometimes. Still, it is better to use this method than to - look at totalTime() and currentTime() to emulate the behavior - because the backend might have more information available than your - application does through totalTime() and currentTime(). - - \sa prefinishMarkReached() -*/ - -/*! - \property Phonon::MediaObject::tickInterval - \brief The time interval in milliseconds between two ticks. - - The tick() signal is emitted continuously during playback. - The tick interval is the time that elapses between the emission of two tick signals. - If you set the interval to \c 0 the tick signal gets disabled. - - The tick() signal can, for instance, be used to update widgets - that show the current position in the playback of a media source. - - Defaults to \c 0 (disabled). - - \warning The back-end is free to choose a different tick interval close - to what you asked for. This means that the following code \c may fail: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 - On the other hand the following is guaranteed: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 - - \sa tick() -*/ - -/*! - \fn Phonon::MediaObject::~MediaObject() - - Destroys the MediaObject. -*/ - -/*! - \fn State Phonon::MediaObject::state() const - - Returns the current Phonon::State of the object. - - \sa Phonon::State, stateChanged() -*/ - -/*! - \fn bool Phonon::MediaObject::hasVideo() const - - Check whether the current media source includes a video stream. - - \warning This information is not resolved immediately after a - media object gets a new source. Listen to the hasVideoChanged() - signal instead. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 - - Returns \c true if the media contains video data; otherwise, - returns \c false. - - \sa hasVideoChanged() -*/ - -/*! - \fn bool Phonon::MediaObject::isSeekable() const - - Check whether it is possible to seek, i.e., change the - playback position in the media stream. - - \warning This information is not solved immediately after the - media object gets a new media source. The hasVideoChanged() signal - is emitted after this information is available. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 - - Returns \c true if the current media may be seeked; otherwise, - returns \c false. - - \sa seekableChanged() -*/ - -/*! - \fn QStringList Phonon::MediaObject::metaData(const QString &key) const - - Returns the strings associated with the given \a key. - - Backends should use the keys specified in the Ogg Vorbis - documentation: \l http://xiph.org/vorbis/doc/v-comment.html - - Therefore the following should work with every backend: - - Note that meta data is not resolved before the \c - metaDataChanged() signal is emitted. - - A typical usage looks like this: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 -*/ - -/*! - \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const - - Returns the strings associated with the given \a key. - - Same as above except that the keys are defined in the - Phonon::MetaData enum. - - \sa metaDataChanged() -*/ - -/*! - \fn QMultiMap Phonon::MediaObject::metaData() const - - Returns all meta data in a multi map. - - \sa metaDataChanged() -*/ - -/*! - \fn QString Phonon::MediaObject::errorString() const - - Returns a human-readable description of the last error that occurred. - The strings given may vary between backends. - - The error description can be used to give a message to the user - - and the developer - when the stateChanged() signal is emitted with - \l{Phonon::}{ErrorState}. - - \section1 Qt Backends - - On Windows, Qt fetches its error messages from the DirectShow - backend. This usually includes an error number, which can be - looked up in the DirectShow documentation: - \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. - - On Linux and Mac, the error strings are not fetched directly from - the backend, but are created in the backend. - - \sa Phonon::ErrorState, stateChanged() -*/ - -/*! - \fn ErrorType Phonon::MediaObject::errorType() const - - Tells your program what to do about the last error that occurred. - Use this function after receiving a stateChanged() signal with - \l{Phonon::}{ErrorState}. - - \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() -*/ - -/*! - \fn MediaSource Phonon::MediaObject::currentSource() const - - Returns the current media source, i.e., the media source that is - being played back. The current source is either set with - setCurrentSource() or taken from the media queue() when a media - source has finished playing. - - \sa setCurrentSource() -*/ - -/*! - \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) - - Set the media source the MediaObject should use. - - After the media object receives a new source, it will enter the - \l{Phonon::}{LoadingState}. When it is ready to play, it - enters the \l{Phonon::}{StoppedState} unless another state - has been requested, e.g., by calling play(). - - \a source is the MediaSource object to the media data. You can - just as well use a QUrl or QString (for a local file) here. - - We show an example: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 - - \sa currentSource(), MediaSource -*/ - -/*! - \fn QList Phonon::MediaObject::queue() const - - Returns the queued media sources. - - This does list does not include the current source, - returned by currentSource(). - - \sa enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::setQueue(const QList &sources) - - Set the \a sources to play when the current source has finished. - - This function will overwrite the current queue. - - \sa clearQueue(), enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::setQueue(const QList &urls) - - Set the \a urls to play when the current media has finished. - - This function overwrites the current queue. - - \sa clearQueue(), enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const MediaSource &source) - - Appends \a source to the queue. - - You can use this function to provide the next source after the - aboutToFinish() signal has been emitted. - - \sa aboutToFinish(), setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const QList &sources) - - Appends multiple \a sources to the queue. - - \sa setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const QList &urls) - - Appends the URLs in \a urls to the media source queue. - - The function will create \l{MediaSource}s from the \l{QUrl}s, and - append these to the queue. - - \sa setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::clearQueue() - - Clears the queue of media sources. - - \sa queue(), enqueue() -*/ - -/*! - \fn qint64 Phonon::MediaObject::currentTime() const - - Returns the current time (in milliseconds), i.e., position in the - media stream, of the file currently being played. - - \sa tick(), totalTime(), remainingTime() -*/ - -/*! - \fn qint64 Phonon::MediaObject::totalTime() const - - Get the total time (in milliseconds) of the file currently being played. - - Returns the total time in milliseconds. - - \warning The total time is not defined before the media object - enters the \l{Phonon::}{LoadingState}. - - \sa totalTimeChanged() -*/ - -/*! - \fn qint64 Phonon::MediaObject::remainingTime() const - - Get the remaining time (in milliseconds) of the file currently being played. - - Returns the remaining time in milliseconds. - - \sa totalTime(), currentTime(), totalTimeChanged() -*/ - -/*! - \fn void Phonon::MediaObject::play() - - Requests playback of the media data to start. - - Playback starts when the stateChanged() signal is emitted with - \l{Phonon::}{PlayingState}. - - If the media object is already in a - \l{Phonon::}{PlayingState}, nothing happens. - - \sa stop(), pause(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::pause() - - Requests playback to pause, and the media object to enter the - \l{Phonon::}{PausedState}. If it was paused already, nothing - changes. - - This function is asynchronous and the media might not be paused - immediately. - - \sa play(), stop(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::stop() - - Requests playback to stop, and the media object to enter the - \l{Phonon::}{StoppedState}. If it was stopped before - nothing changes. - - This function is asynchronous and the media might not be - stopped immediately. - - \sa play(), pause(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::seek(qint64 time) - - Requests a seek to the \a time indicated, specified in milliseconds. - - You can only seek if state() is PlayingState, BufferingState or PausedState. - - The call is asynchronous, so currentTime can still be the old - value right after this method was called. If all you need is a - slider that shows the current position and allows the user to - seek, use the class SeekSlider. - - If the current source of the media object is not seekable, calls - to this functions do nothing. - - \sa SeekSlider, tick() -*/ - -/*! - \fn void Phonon::MediaObject::clear() - - Stops and removes all playing and enqueued media sources. - - \sa setCurrentSource() -*/ - - -/*! - \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) - - This signal is emitted when the state of the MediaObject has changed. - The \a oldstate and \a newstate parameters indicate the previous - state and current state of the media object. - - If you are only interested in the new state of the media object, you can - connect this signal to a slot that accepts only one State argument. -*/ - -/*! - \fn void Phonon::MediaObject::tick(qint64 time) - - This signal is emitted in intervals defined by the - \l{tickInterval} property. The current position of the media - object in the stream is given by the \a time parameter. The \a - time is specified in milliseconds. - - \sa tickInterval -*/ - -/*! - \fn void Phonon::MediaObject::metaDataChanged() - - This signal is emitted when the media object has resolved new meta - data. This will happen before the media object leaves the - \l{Phonon::}{LoadingState} after a new source has been set. - - This signal is not emitted when the media object removes the - current data, i.e., when a new source is set or an error has - occurred. If you need to know this, you can listen for the - \l{Phonon::}{ErrorState}, and connect to the - \l{Phonon::MediaObject::}{currentSourceChanged()} signal. - - You can get the new meta data with the metaData methods. - - \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State -*/ - -/*! - \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) - - This signal is emitted when the media object's ability to seek in - the media stream changes. \a isSeekable is true if it is possible - to seek(); otherwise, it is false. - - Change in the ability to seek in the stream usually happens when - the current source changes or when an error occurs. - - \omit Emitted whenever the return value of isSeekable() - changes. \endomit - - Normally you'll check isSeekable() after setting a new media - source, and then let this signal tell you when seeking is - possible. That way you don't have to poll isSeekable(). -*/ - -/*! - \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) - - Emitted whenever the return value of hasVideo() changes, i.e., - the media source being played back contains video. - - Normally you'll check hasVideo() first and then let this signal - tell you whether video is available now or not. That way you - don't have to poll hasVideo(). - - \a hasVideo is true when the stream contains video and adding a - VideoWidget will show a video, and false if there is no video data - in the stream and adding a VideoWidget will show an empty (black) - VideoWidget. -*/ - -/*! - \fn void Phonon::MediaObject::bufferStatus(int percentFilled) - - Provides information about the status of the buffer. - - When a MediaObject is in the \l{Phonon::}{BufferingState}, it will - send this signal regularly. \a percentFilled is a number between 0 - and 100 telling you how much the buffer is filled. - - You can use this signal to show a progress bar to the user when - in BufferingState: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 - - Note that the \l{Phonon::}{BufferingState} is commonly used when - waiting for data over a network connection, but this might not be - true for all backends. -*/ - -/*! - \fn void Phonon::MediaObject::finished() - - Emitted when the object has finished playback. It is not emitted - if you call stop(), pause() or load(). It is emitted only when the - current media source has finished playing and the media queue() is - empty, or when a \l{Phonon::FatalError}{fatal error} occurs. - - \warning This signal is not emitted when the current source has - finished and there's another source in the queue. It is only - emitted when the queue is empty. - - \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() -*/ - -/*! - \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) - - Emitted when the MediaObject fetches a new MediaSource from the - queue() and before it enters the \l{Phonon::}{LoadingState} for - the new source. The media object will take a new source from the - queue() when it has finished the playback of the - \l{currentSource()}{current source}. - - \a newSource is the source that starts to play at the time the - signal is emitted. -*/ - -/*! - \fn void Phonon::MediaObject::aboutToFinish() - - Emitted before the playback of the whole queue ends. When this - signal is emitted you still have time to enqueue() a new - MediaSource, so that playback continues. - - If you need a signal to be emitted at a specific time before - playback is finished, you should use the prefinishMarkReached() - signal instead. - - \sa enqueue(), prefinishMark, prefinishMarkReached() -*/ - -/*! - \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) - - Emitted when there are only \a msecToEnd milliseconds left - of playback. - - \warning This signal is not emitted when there is another source - in the queue. It is only emitted when the queue is empty. - - \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() -*/ - -/*! - \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) - - This signal is emitted as soon as the total time of the media file is - known or has changed. For most non-local media data the total - time of the media can only be known after some time. At that time the - totalTime function can not return useful information. You have - to wait for this signal to know the real total time. - - \a newTotalTime is the length of the media file in milliseconds. - - \sa totalTime() -*/ - -/*! - \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) - - Convenience function to create a MediaObject and AudioOutput - connected by a path. The \l{Phonon::}{MediaObject} return will - have \a source set as its current source and the specified \a - category. - -*/ - -/*! - \class Phonon::MediaObjectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \namespace Phonon::BackendCapabilities - \inmodule Phonon - \since 4.4 - \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. - -*/ - -/*! - \class Phonon::BackendCapabilitiesPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::BackendCapabilities::Notifier - \since 4.4 - \inmodule Phonon - \inheaderfile Phonon/BackendCapabilities - - Notifications about backend capabilities. -*/ - -/*! - \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() - - This signal is emitted if the capabilities have changed. This can - happen if the user has requested a backend change. -*/ - -/*! - \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() - - This signal is emitted when audio output devices were plugged or - unplugged. - - Check BackendCapabilities::availableAudioOutputDevices to get the - current list of available devices. -*/ - -/*! - \fn Notifier *Phonon::BackendCapabilities::notifier() - - Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. - - \return a pointer to a QObject. - - The capabilitiesChanged signal is emitted if the capabilities have changed. This can - happen if the user has requested a backend change. - - To connect to this signal do the following: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 - - \sa Notifier::capabilitiesChanged() -*/ - -/*! - \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() - - Returns a list of mime types that the Backend can decode. - - \sa isMimeTypeAvailable() -*/ - -/*! - \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) - - Often all you want to know is whether one given MIME type can be - decoded by the backend. Use this method in favor of - availableMimeTypes() as it can give you a negative answer without - having a backend loaded. - - Returns true if the given \a mimeType is supported by the backend; - otherwise, returns false. - - \sa availableMimeTypes() -*/ - -/*! - \fn QList Phonon::BackendCapabilities::availableAudioOutputDevices() - - Returns the audio output devices the backend supports. - - \return A list of AudioOutputDevice objects that give a name and - description for every supported audio output device. -*/ - -/*! - \fn QList Phonon::BackendCapabilities::availableAudioEffects() - - Returns descriptions for the audio effects the backend supports. - - \return A list of AudioEffectDescription objects that give a name and - description for every supported audio effect. -*/ - -/*! - \internal - \class ObjectDescriptionModelData - \internal - \inmodule Phonon - \brief Data class for models for ObjectDescription objects. -*/ - -/*! - \typedef Phonon::EffectDescription - \relates Phonon::ObjectDescription - - EffectDescription gives a description of an \l{Processors}{audio - effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} - class. Please see its class description for details. - - EffectDescription is used to create audio \l{Phonon::}{Effect}s, - which can be inserted into a media graph, altering an audio - stream. - - \sa Phonon::ObjectDescription, {Capabilities Example}, {Media - Player} - -*/ - -/*! - \class Phonon::ObjectDescriptionModel - \inmodule Phonon - \internal - \since 4.4 - \brief The ObjectDescriptionModel class provides a model from - a list of ObjectDescription objects. - - ObjectDescriptionModel is a read only model that supplies a list - using ObjectDescription::name() for the text and - ObjectDescription::description() for the tooltip. If set the properties - "icon" and "available" are used to set the decoration and disable the - item (disabled only visually, you can still select and drag it). - - It also provides the methods moveUp() and moveDown() to order the list. - Additionally drag and drop is possible so that - QAbstractItemView::InternalMove can be used. - The resulting order of the ObjectDescription::index() values can then be - retrieved using tupleIndexOrder(). - - An example use case would be to give the user a QComboBox to select - the output device: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 - - And to retrieve the selected AudioOutputDevice: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 - -*/ - -/*! - \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const - - Returns the number of rows in the model. This value corresponds - to the size of the list passed through setModelData. - - \param parent The optional \a parent argument is used in most models to specify - the parent of the rows to be counted. Because this is a list if a - valid parent is specified the result will always be 0. - - Reimplemented from QAbstractItemModel. - - \sa QAbstractItemModel::rowCount() -*/ - -/*! - \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const - - Returns data from the item with the given \a index for the specified - \a role. - If the view requests an invalid index, an invalid variant is - returned. - - Reimplemented from QAbstractItemModel. - - \sa QAbstractItemModel::data(), Qt::ItemDataRole -*/ - -/*! - \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const - \internal - - Reimplemented to show unavailable devices as disabled (but still - selectable). The \a index of the model index for which to return - flags. - -*/ - -/*! - \fn inline QList Phonon::ObjectDescriptionModel::tupleIndexOrder() const - - Returns a list of indexes in the same order as they are in the - model. The indexes come from the ObjectDescription::index - method. - - This is useful to let the user define a list of preference. -*/ - -/*! - \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const - - Returns the ObjectDescription::index for the tuple - at the given position \a positionIndex. For example a - QComboBox will give you the currentIndex as the - position in the list. But to select the according - AudioOutputDevice using AudioOutputDevice::fromIndex - you can use this method. - - \param positionIndex The position in the list. -*/ - -/*! - \class Phonon::ObjectDescriptionModelDataPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const - \internal - - Returns the MIME data that dropMimeData() can use to create new - items. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) - - Moves the item at the given \a index up. In the resulting list - the items at index.row() and index.row() - 1 are swapped. - - Connected views are updated automatically. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) - - Moves the item at the given \a index down. In the resulting list - the items at index.row() and index.row() + 1 are swapped. - - Connected views are updated automatically. -*/ - -/*! - \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) - - Constructs a ObjectDescription model with the - given \a parent. -*/ - -/*! - \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList > &data, QObject *parent = 0) - - Constructs a ObjectDescription model with the - given \a parent and the given \a data. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList > &data) - - Sets the model data using the list provided by \a data. - - All previous model data is cleared. -*/ - -/*! - \fn inline QList > Phonon::ObjectDescriptionModel::modelData() const - - Returns the model data. - - As the order of the list might have changed this can be different - to what was set using setModelData(). -*/ - -/*! - \fn inline ObjectDescription Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const - - Returns one ObjectDescription of the model data for the given \a index. -*/ - -/*! - \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const - - This model supports drag and drop to copy or move - items. -*/ - -/*! - \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) - - Accept drops from other models of the same ObjectDescriptionType. - - The \a data is dropped at the given \a row and \a column; you - also receive the \a parent model index. - - If a valid \a parent is given the dropped items will be inserted - above that item. -*/ - -/*! - \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) - - Removes count rows starting with the given row. - - If a valid \a parent is given no rows are removed since this is a - list model. - - Returns true if the rows were successfully removed; otherwise returns false. -*/ - -/*! - \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const - - Returns a list of supported drag and drop MIME types. Currently - it only supports one type used internally. -*/ - -/*! - \class Phonon::EffectInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::Effect - \inmodule Phonon - \inheaderfile Phonon/Effect - \since 4.4 - \brief The Effect class is used to transform audio streams. - - An effect is a media node which is inserted into a path between a - \l{Phonon::}{MediaObject} and an audio output node, for instance, - an \l{Phonon::}{AudioOutput}. The Effect transforms the media - stream on that path. - - Examples may include simple modifiers, such as fading or pitch - shifting, and more complex mathematical transformations. You can - query the backend for available effects with - BackendCapabilities::availableAudioEffects(). Note that the - effects available is dependent on the underlying system - (DirectDraw, GStreamer, or QuickTime). - - In order to use an effect, insert it into the path as follows: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 - - The effect will immediately begin applying it's transformations on - the path. To stop it, remove the Effect from the path. - - To create an effect, you use the \l{Phonon::}{EffectDescription} - class, which you get from - \l{BackendCapabilities::}{availableAudioEffects()}. We give a code - example below. - - \snippet doc/src/snippets/audioeffects.cpp 0 - - An effect can have one or more parameters, which let you alter how - the effect works, for instance, by specifying the depth of a - reverb effect. See the EffectParameter class description for - details. - - Phonon also provides EffectWidget, which lets the user modify the - parameters of an effect an the fly; e.g., with combo boxes. - - \sa {Phonon Module}, EffectWidget -*/ - -/*! - \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) - - Constructs a new effect object with the given \a description and \a parent object. - - The EffectDescription object determines the type of the effect. - - \sa {Phonon::BackendCapabilities::availableAudioEffects()} -*/ - -/*! - \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) - \internal -*/ - -/*! - \fn Phonon::Effect::~Effect() - \internal -*/ - -/*! - \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const - - Returns the value of the given effect \a parameter. You can fetch - the available parameters for an effect with parameters(). - - \sa setParameterValue(), EffectParameter -*/ - -/*! - \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) - - Sets the given effect \a parameter to the specified \a value. - - Parameters for an effect are returned by parameters(). You can - check which QVariant::Type an EffectParameter takes with the - EffectParameter::type() function. - - \sa parameterValue(), EffectParameter -*/ - -/*! - \fn EffectDescription Phonon::Effect::description() const; - - Returns the description of this effect. This is the same - description that was passed to the constructor. -*/ - -/*! - \fn QList Phonon::Effect::parameters() const; - - Returns a list of parameters that this effect provides to control - its behavior. - - \sa EffectParameter, EffectWidget -*/ - -/*! - \class Phonon::EffectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::AudioOutput - \inmodule Phonon - \inheaderfile Phonon/AudioOutput - \since 4.4 - \brief The AudioOutput class is used to send data to audio output devices. - - The AudioOutput class plays sound over a sound device. The audio - output needs to be connected to a \l{Phonon::}{MediaObject} using - \l{Phonon::}{createPath()}. To start playback, you call - \l{Phonon::MediaObject::}{play()} on the media object. - - \snippet snippets/phonon.cpp 2 - - The class supports changing the volume(). It is also possible to - mute the sound. - - To find out what \l{Phonon::}{AudioOutputDevice}s are available - for AudioOutput, you can call - BackendCapabilities::availableAudioOutputDevices(). A default device is - selected by the backend, but it is possible to set the device to - be used with setOutputDevice(). The outputDeviceChanged() signal - will be emitted if the device changes. - - If an error occurs with the playback, for instance, if no valid - output device is found, the media object will receive a - stateChanged() signal with the \l{Phonon::}{ErrorState}. - - Note that the default values of properties are dependent on the - backend. - - \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} -*/ - -/*! - \property Phonon::AudioOutput::name - - This is the name that appears in Mixer applications that control - the volume of this output. - -*/ - -/*! - \property Phonon::AudioOutput::volume - - This is the current loudness of the output. \omit The volume is a - real value between 0.0 (minimum) and 1.0 (maximum). The volume - follows the sound device used, with 1.0 being the maximum volume - the device can produce. \endomit - - (it is using Stevens' law - to calculate the change in voltage internally). - - \sa volumeDecibel -*/ - -/*! - \property Phonon::AudioOutput::volumeDecibel - - This is the current volume of the output in decibel. - - 0 dB means no change in volume, -6dB means an attenuation of the - voltage to 50% and an attenuation of the power to 25%, -inf dB means - silence. - - \sa volume -*/ - -/*! - \property Phonon::AudioOutput::outputDevice - This property holds the (hardware) destination for the output. - - The default device is determined by the \l{Phonon::}{Category} and the global - configuration for that category. Normally you don't need - to override this setting - letting the user change the global - configuration is the right choice. You can still override the - device though, if you have good reasons to do so. - - \sa outputDeviceChanged() -*/ - -/*! - \property Phonon::AudioOutput::muted - This property tells whether the output is muted. - - Muting the output has the same effect as calling setVolume(0.0). -*/ - -/*! - \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) - - Creates a new AudioOutput with the given \a parent that defines - output to a physical device. - - The \a category can be used by mixer applications to group volume - controls of applications into categories. That makes it easier for - the user to identify the programs. - The category is also used for the default output device that is - configured centrally. As an example: often users want to have the - audio signal of a VoIP application go to their USB headset while - all other sounds should go to the internal soundcard. - - \sa Phonon::categoryToString(), outputDevice -*/ - -/*! - \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) - - Creates a new AudioOutput that defines output to the system - default device with the \{Phonon::Category::}{NoCategory} category - - \sa Phonon::categoryToString(), outputDevice -*/ - -/*! - \fn Phonon::Category Phonon::AudioOutput::category() const - - Returns the category of this output. - - \sa Phonon::AudioOutput::AudioOutput() -*/ - -/*! - \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) - - This signal is emitted whenever the volume has changed. As the - volume can change without a call to setVolume (calls over dbus) - this is important to keep a widget showing the current volume up - to date. - - \a newVolume is the new volume level. - - \sa setVolume(), volume() -*/ - -/*! - \fn void Phonon::AudioOutput::mutedChanged(bool muted) - - This signal is emitted when the muted property has changed. The \a muted - value passed by the signal indicates the state of the muted property. - As this property can change by IPC (DBus) calls a UI element showing - the muted property should listen to this signal. -*/ - -/*! - \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) - - This signal is emitted when the (hardware) device for the output - has changed. \a newAudioOutputDevice is the new device. - - The change can happen either through setOutputDevice or if the - global configuration for the used category has changed. - - \sa outputDevice -*/ - -/*! - \class Phonon::AudioOutputPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectParameter - \inmodule Phonon - \inheaderfile Phonon/EffectParameter - \since 4.4 - \brief The EffectParameter class describes one parameter of an effect. - - You fetch the parameters of an \l{Phonon::}{Effect} with - \l{Phonon::}{Effect::parameters()}. - - \snippet doc/src/snippets/phononeffectparameter.cpp 0 - - To describe itself, an effect parameter gives a name() and - possibly description() (depending on the backend used). These are - suited to present the effect parameter to the user of a Phonon - application. - - Note that effects are created by the backend, and that - their name and descriptions may vary. - - The value of an effect parameter is stored in a \l{QVariant}, - of which type() is usually \c int or \c double. - - The value is retrieved with \l{Phonon::}{Effect::parameterValue()} - and set with \l{Phonon::Effect::}{setParameterValue()} - both of - which takes the EffectParameter as argument. Note that not all - effect parameters support setting of their value. - - You get the values a parameter can take with possibleValues(); an - empty list is returned if the values are continuous. - - A parameter may also specify default(), minimum(), and maximum() - values. Values are returned as \l{QVariant}s. If the parameter - does not have the requested value, an \l{QVariant::Invalid} - invalid QVariant is returned from these functions. - - The \l{Phonon::}{EffectWidget} provides a widget with which one - can control the parameters of an \l{Phonon::}{Effect}. - - \snippet doc/src/snippets/phononeffectparameter.cpp 1 - - \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter() - \internal - - Creates an invalid effect parameter. -*/ - -/*! - \fn Phonon::EffectParameter::~EffectParameter() - - Destroys the effect parameter. -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) - - Constructs a copy of the \a other effect parameter. -*/ - -/*! - \fn const QString &Phonon::EffectParameter::name() const - - The name of the parameter. Can be used as the label. - - \return A label for the parameter. -*/ - -/*! - \fn const QString &Phonon::EffectParameter::description() const - - The parameter may come with a description (LADSPA doesn't have a - field for this, so don't expect many effects to provide a - description). - - The description can be used for a tooltip or WhatsThis help. - - \return A text describing the parameter. -*/ - -/*! - \fn QVariant::Type Phonon::EffectParameter::type() const - - Returns the parameter type. - - Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When - QVariant::String is returned you get the possible values from possibleValues. -*/ - -/*! - \fn bool Phonon::EffectParameter::isLogarithmicControl() const - - Returns whether the parameter should be - displayed using a logarithmic scale. This is particularly useful for - frequencies and gains. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::minimumValue() const - - The minimum value to be used for the control to edit the parameter. - - If the returned QVariant is invalid the value is not bounded from - below. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::maximumValue() const - - The maximum value to be used for the control to edit the parameter. - - If the returned QVariant is invalid the value is not bounded from - above. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::defaultValue() const - - The default value. -*/ - -/*! - \fn QVariantList Phonon::EffectParameter::possibleValues() const - - The possible values to be used for the control to edit the parameter. - - if the value of this parameter is to be picked from predefined values - this returns the list (otherwise it returns an empty QVariantList). -*/ - -/*! - \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) - - Assigns the \a other effect parameter to this parameter and returns - a reference to this parameter. -*/ - -/*! - \enum Phonon::EffectParameter::Hint - - Only for backend developers: - - Flags to set the return values of isToggleControl(), - isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and - isBoundedAbove(). The values of the flags correspond to the values - used for LADSPA effects. - - \value ToggledHint - If this hint is set it means that - the control has only two states: zero and non-zero - (see isToggleControl()). - - \value LogarithmicHint - LADSPA's SAMPLE_RATE hint needs to be translated by the backend - to normal bounds, as the backend knows the sample rate - and the - frontend doesn't (see isLogarithmicControl()). - - \value IntegerHint See isIntegerControl(). -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter(int parameterId, - const QString &name, EffectParameter::Hints hints, - const QVariant &defaultValue, const QVariant &min = QVariant(), - const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), - const QString &description = QString()) - - Only to be used by backend implementations: - - Creates a new effect parameter. - - \a parameterId This is a number to uniquely identify the - parameter. The id is used for value() and setValue(). - - \a name is the name/label for this parameter. - - \a hints sets the hints for the type of parameter. - - \a defaultValue The value that should be used as a default. - - \a min is the minimum value allowed for this parameter. You only - need to set this if the BoundedBelowHint is set. - - \a max is the maximum value allowed for this parameter. You only - need to set this if the BoundedAboveHint is set. - - The \a values parameter is the values that the effect parameter - can take (only applies if non-continuous) - - \a description is a descriptive text for the parameter - (explaining what it controls) to be used as a tooltip or - WhatsThis help. -*/ - -/*! - \fn int Phonon::EffectParameter::id() const - - \internal - - Returns the parameter's identifier. -*/ - -/*! - \typedef Phonon::AudioOutputInterface - \inmodule Phonon - \internal -*/ - -/*! - \class Phonon::AudioOutputInterface40 - \inmodule Phonon - \since 4.4 - \internal - \brief Interface for AudioOutput objects - -*/ - -/*! - \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() - \internal -*/ - -/*! - \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 - \internal -*/ - -/*! - \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 - \internal -*/ - -/*! - \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 - \internal -*/ - -/*! - \class Phonon::Path - \inmodule Phonon - \inheaderfile Phonon/Path - \since 4.4 - \brief The Path class describes connections between media nodes. - - In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s - are connected by Paths. The multimedia travels in streams over - these paths. - - You create a path between two media nodes using the static - Phonon::createPath() function, which takes two nodes as arguments. - The first argument will send the media stream to the second. - Please refer to the class description of the individual media - nodes and the Phonon \l{Phonon Overview}{overview} to see which - nodes can be connected to each other. - - Paths are also used to insert audio \l{Phonon::}{Effect}s between - two media nodes. The effect will then alter the stream on the - path. Notice that \l{Phonon::}{Effect}s also are media nodes, but - that insertEffect() - instead of Phonon::createPath() - is used to - insert them into the media graph. - - The following code example shows how to create a path between two - media nodes and insert an effect on that path. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 - - \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, - Phonon::VideoWidget, {Phonon Module} -*/ - -/*! - \fn Phonon::Path::~Path(); - - Destroys this reference to the Path. If the path was valid the connection is not broken - as both the source and the sink MediaNodes still keep a reference to the Path. - - \sa disconnect() -*/ - -/*! - \fn Phonon::Path::Path(); - - Creates an invalid path. - - You can still make it a valid path by calling reconnect. It is - recommended to use the Phonon::createPath() function to create - paths. - - \sa Phonon::createPath(), isValid() -*/ - -/*! - \fn Phonon::Path::Path(const Path &path); - - Constructs a copy of the other \a path specified. - - This constructor is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::Path::isValid() const; - - A path is considered valid if it is connected to two media nodes, - in which case this function returns true. If it is connected to - one or no media nodes, it is consider invalid, and this function - will then return false. -*/ - -/*! - \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); - - Creates and inserts an effect into the path. - - You may insert effects of the same class as often as you like, - but if you insert the same object, the call will fail. - - \a desc is the EffectDescription object for the effect to be inserted. - - If you already inserted an effect you can - tell with \a insertBefore in which order the data gets - processed. If this is \c 0 the effect is appended at the end of - the processing list. If the effect has not been inserted before - the method will do nothing and return \c false. - - Returns a pointer to the effect object if it could be inserted - at the specified position. If \c 0 is returned, the effect was not - inserted. - - Below is a code example for inserting an effect into a path: - - \snippet doc/src/snippets/audioeffects.cpp 0 - - \sa removeEffect(), effects() -*/ - -/*! - \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); - - Inserts the given \a effect into the path before the effect specified by \a insertBefore - and returns true if successful; otherwise returns false. - - If \a insertBefore is zero, the effect is appended to the processing list. - - You may insert effects of the same class as often as you like, but if you insert - the same object, the call will fail. - - \a effect will be inserted right before \a insertBefore. If - \a insertBefore is \c 0, the effect is appended at the end of the - processing list. If the effect has not been inserted before the - method will do nothing and return \c false. - - Returns whether the effect could be inserted at the specified - position. If \c false is returned the effect was not inserted. - - \sa removeEffect(), effects() -*/ - -/*! - \fn bool Phonon::Path::removeEffect(Effect *effect); - - Removes the given \a effect from the path and returns true; otherwise returns false. - - Removes an \a effect from the path. - - If the effect is deleted while it is still connected, the effect will be removed - automatically. - - \omit - \param effect The effect to be removed. - - \return Returns whether the call was successful. If it returns - \c false the effect could not be found in the path, meaning it - has not been inserted before. - \endomit - - \sa insertEffect(), effects() -*/ - -/*! - \fn QList Phonon::Path::effects() const; - - Returns a list of Effect objects that are currently - used as effects. The order in the list determines the order the - signal is sent through the effects. - - \return A list with all current effects. - - \sa insertEffect(), removeEffect() -*/ - -/*! - \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); - - Changes the media nodes the path is connected to by connecting the path - to the \a source and \a sink nodes specified. Returns true if successful; - otherwise returns false. - - If unsuccessful, the path remains connected to the same nodes as before. - - \sa Phonon::createPath(), {Phonon Overview} -*/ - -/*! - \fn bool Phonon::Path::disconnect(); - - Tries to disconnect the path from the MediaNodes it is connected to, returning - true if successful or false if unsuccessful. - - If successful, the path is invalidated: isValid() will returns false. -*/ - -/*! - \fn Path &Phonon::Path::operator=(const Path &p); - - Assigns \a p to this Path and returns a reference to this Path. - - This operation is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::Path::operator==(const Path &p) const; - - Returns true if this Path is equal to \a p; otherwise returns false; -*/ - -/*! - \fn bool Phonon::Path::operator!=(const Path &p) const; - - Returns true if this Path is not equal to \a p; otherwise returns false. -*/ - -/*! - \fn MediaNode *Phonon::Path::source() const; - - Returns the source MediaNode used by the path. -*/ - -/*! - \fn MediaNode *Phonon::Path::sink() const; - - Returns the sink MediaNode used by the path. -*/ - -/*! - \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); - - \relates Phonon::Path - Creates a new Path connecting the two MediaNodes \a source and \a sink. - - The implementation will automatically select the right format and media type. E.g. connecting a - MediaObject and AudioOutput will create a Path object connecting the audio. This might be - represented as PCM or perhaps even AC3 depending on the AudioOutput object. - - \param source The MediaNode to connect an output from - \param sink The MediaNode to connect to. -*/ - -/*! - \class Phonon::PathPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaObjectInterface - \inmodule Phonon - \since 4.4 - \internal - \brief Backend interface for media sources. - - The backend implementation has to provide two signals, that are not defined - in this interface: - \list - \o \target phonon_MediaObjectInterface_stateChanged - void stateChanged(Phonon::State newstate, Phonon::State oldstate) - - Emitted when the state of the MediaObject has changed. - In case you're not interested in the old state you can also - connect to a slot that only has one State argument. - - \param newstate The state the Player is in now. - \param oldstate The state the Player was in before. - - \o \target phonon_MediaObjectInterface_tick - void tick(qint64 time) - - This signal gets emitted every tickInterval milliseconds. - - \param time The position of the media file in milliseconds. - - \sa setTickInterval() - \sa tickInterval() - \endlist - - \sa MediaObject -*/ - -/*! - \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() - \internal -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const - \internal -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 - \internal -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::play() = 0 - \internal - - Requests the playback to start. - - This method is only called if the state transition to PlayingState is possible. - - The backend should react immediately - by either going into PlayingState or BufferingState if the - former is not possible. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::pause() = 0 - \internal - - Requests the playback to pause. - - This method is only called if the state transition to PausedState is possible. - - The backend should react as fast as possible. Go to PausedState - as soon as playback is paused. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::stop() = 0 - \internal - - Requests the playback to be stopped. - - This method is only called if the state transition to StoppedState is possible. - - The backend should react as fast as possible. Go to StoppedState - as soon as playback is stopped. - - A subsequent call to play() will start playback at the beginning of - the media. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 - \internal - - Requests the playback to be seeked to the given time. - - The backend does not have to finish seeking while in this function - (i.e. the backend does not need to block the thread until the seek is - finished; even worse it might lead to deadlocks when using a - ByteStream which gets its data from the thread this function would - block). - - As soon as the seek is done the currentTime() function and - the tick() signal will report it. - - \param milliseconds The time where playback should seek to in - milliseconds. -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 - \internal - - Return the time interval in milliseconds between two ticks. - - Returns the tick interval that it was set to (might not - be the same as you asked for). -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 - \internal - - Change the interval the tick signal is emitted. Set \a interval to 0 to - disable the signal. - - \a interval tick interval in milliseconds - - Returns the tick interval that it was set to (might not be the same as you - asked for). - -*/ - -/*! - \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 - \internal - - Check whether the media data includes a video stream. - - Returns true if the media contains video data. -*/ - -/*! - \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 - \internal - - If the current media may be seeked this function returns true; - otherwise, false. - - Returns whether the current media may be seeked. -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 - \internal - - Get the current time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 - \internal - - Get the current state. -*/ - -/*! - \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 - \internal - - A translated string describing the error. -*/ - -/*! - \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 - \internal - - Tells your program what to do about the error. - - \sa Phonon::ErrorType -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 - \internal - - Returns the total time of the media in milliseconds. - - If the total time is not know return -1. Do not block until it is - known, instead emit the totalTimeChanged signal as soon as the total - time is known or changes. -*/ - -/*! - \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 - \internal - - Returns the current source. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 - \internal - - Sets the current source. When this function is called the MediaObject is - expected to stop all current activity and start loading the new - source (i.e. go into LoadingState). - - It is expected that the - backend now starts preloading the media data, filling the audio - and video buffers and making all media meta data available. It - will also trigger the totalTimeChanged signal. - - If the backend does not know how to handle the source it needs to - change state to Phonon::ErrorState. Don't bother about handling KIO - URLs. It is enough to handle AbstractMediaStream sources correctly. - - \warning Keep the MediaSource object around as long as the backend - uses the AbstractMediaStream returned by the MediaSource. In case - that no other reference to the MediaSource exists and it is set to - MediaSource::autoDelete, the AbstractMediaStream is deleted when the - last MediaSource ref is deleted. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 - \internal - - Sets the next source to be used for transitions. When a next source - is set playback should continue with the new source. In that case - finished and prefinishMarkReached are not emitted. - - \param source The source to transition to (crossfade/gapless/gap). If - \a source is an invalid MediaSource object then the queue is empty - and the playback should stop normally. - - \warning Keep the MediaSource object around as long as the backend - uses the AbstractMediaStream returned by the MediaSource. In case - that no other reference to the MediaSource exists and it is set to - MediaSource::autoDelete, the AbstractMediaStream is deleted when the - last MediaSource ref is deleted. -*/ - -/*! - \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget - \inmodule Phonon - \inheaderfile Phonon/EffectWidget - \since 4.4 - \brief The EffectWidget class provides a widget to control the parameters of an Effect. - - The EffectWidget class provides a widget, with which an effects - parameters can be controlled. The widget does not have an API, - and is constructed with the \l{Phonon::}{Effect}, of which - parameters should be controlled. - - \snippet doc/src/snippets/audioeffects.cpp 1 - - The following image shows an example of an effect widget. - - \image effectwidget.png - - Note that some audio effects do not have parameters, and the - widget will then not \l{QWidget::}{show()} at all. - - \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} -*/ - -/*! - \class Phonon::AbstractAudioOutput - \inmodule Phonon - \internal - \brief Provides a common base class for all audio outputs. - - \sa AudioOutput -*/ - -/*! - \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() - \internal -*/ - -/*! - \class Phonon::AbstractAudioOutputPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class AudioOutputAdaptor - \inmodule Phonon - \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput - \internal -*/ - -/*! - \class Phonon::VolumeSlider - \inmodule Phonon - \inheaderfile Phonon/VolumeSlider - \since 4.4 - \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. - - The slider also displays an icon indicating if the volume of the - \l{Phonon::}{AudioOutput} it is connected to is muted. The icon - can be removed with setMuteVisible(). - - It is possible to set the \l{maximumVolume}{maximum} value of the - slider. By default, the minimum and maximum values of the slider - are 0.0 (no sound) to 1.0 (the maximum volume the audio output can - produce). - - Here follows a code example: - - \snippet doc/src/snippets/volumeslider.cpp 0 - - \omit mention how to change the style of the slider. \endomit - - \sa {Phonon Module} -*/ - -/*! - \property Phonon::VolumeSlider::maximumVolume - - This property holds the maximum volume that can be set with this slider. - - By default the maximum value is 1.0 (100%). -*/ - -/*! - \property Phonon::VolumeSlider::orientation - This property holds the orientation of the slider. - - The orientation must be Qt::Vertical (the default) or Qt::Horizontal. -*/ - -/*! - \property Phonon::VolumeSlider::tracking - This property holds whether slider tracking is enabled. - - If tracking is enabled (the default), the volume changes - while the slider is being dragged. If tracking is - disabled, the volume changes only when the user - releases the slider. -*/ - -/*! - \property Phonon::VolumeSlider::pageStep - This property holds the page step. - - The larger of two natural steps that a slider provides and - typically corresponds to the user pressing PageUp or PageDown. - - Defaults to 5 (5% of the voltage). -*/ - -/*! - \property Phonon::VolumeSlider::singleStep - This property holds the single step. - - The smaller of two natural steps that a slider provides and - typically corresponds to the user pressing an arrow key. - - Defaults to 1 (1% of the voltage). -*/ - -/*! - \property Phonon::VolumeSlider::muteVisible - This property holds whether the mute button/icon next to the slider is visible. - - By default the mute button/icon is visible. -*/ - -/*! - \property Phonon::VolumeSlider::iconSize - \brief the icon size used for the mute button/icon. - - The default size is defined by the GUI style. -*/ - -/*! - \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) - Constructs a new volume slider with the given \a parent. -*/ - -/*! - \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) - Constructs a new volume slider with the given \a output object and \a parent. -*/ - -/*! - \fn Phonon::VolumeSlider::~VolumeSlider() -*/ - -/*! - \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const -*/ - -/*! - \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) - - Sets the audio output object to be controlled by this slider to the specified - \a output object. -*/ - -/*! - \class Phonon::VolumeSliderPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaController - \inmodule Phonon - \inheaderfile Phonon/MediaController - \since 4.4 - \brief The MediaController class controls optional features of a media file/device. - - Some media sources have content that the \l{Phonon::}{MediaObject} - does not provide control over, for instance, chapters in a DVD - file. The functionality the media controller offers is - dependent on the type of media source that is played back. - Commonly, the media controller allows you to: - - \list - \o Navigate between \bold chapters. - \o Navigate between \bold titles. - \o Select between \bold angles. - \endlist - - The \l{Phonon::MediaController::}{Feature} enum explains these - terms in more detail, and their context in playback of CD and DVD. - - The media controller keeps a \l{Phonon::}{MediaObject}, of which - \l{Phonon::MediaObject::currentSource()}{media source} is played - back. You can still call the media object's functions, e.g., - \l{Phonon::MediaObject::}{stop()}; this is all handled correctly - by the media controller. You have the option of letting the media - controller play all titles of a source in sequence by setting the - \l{autoplayTitles()}{autoplay titles} option. - - To start a playback using a media object, you call - \l{Phonon::MediaObject::}{play()} on the media object. To play a - specific title, use setCurrentTitle() and then call - \l{Phonon::MediaObject::}{play()}. - - \warning The Phonon::MediaController class is not yet supported by - Qt backends. - - \sa {Phonon Module} -*/ - -/*! - \fn int Phonon::MediaController::availableAudioChannels() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::availableAudioChannelsChanged() - \internal -*/ - -/*! - \fn QList Phonon::MediaController::availableSubtitles() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::availableSubtitlesChanged() - \internal -*/ - -/*! - \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const - \internal -*/ - -/*! - \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) - \internal -*/ - -/*! - \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) - \internal -*/ - -/*! - \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() - \internal -*/ - -/*! - \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() - \internal -*/ - -/*! - \enum Phonon::MediaController::Feature - - The values of this enum are interpreted differently depending on - the type of media source, e.g., DVD or CD. We give examples for - these sources. - - \value Angles In the VOB (DVD) format, it is possible to to give - several video streams of the same scene, each of which displays - the scene from a different angle. The DVD viewer can then change - between these angles. - - \value Chapters In the VOB format, chapters are points in a - single video stream that can be played and seeked to - separately. - - \value Titles On a CD, a title is a separate sound track. On DVD, - a title is a separate VOB file. - -*/ - -/*! - \fn Phonon::MediaController::MediaController(MediaObject *parent) - - Constructs a new MediaController with the media object (\a parent) - to be used by the media controller. - - \sa MediaObject, Feature -*/ - -/*! - \fn Phonon::MediaController::~MediaController() -*/ - -/*! - \fn Features Phonon::MediaController::supportedFeatures() const -*/ - -/*! - \fn int Phonon::MediaController::availableAngles() const - - Returns the available angles that is available for the current - media source. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentAngle() const - - Returns the angle that is currently used. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::availableChapters() const - - Returns the number of chapters the current media source - contains. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentChapter() const - - Returns the chapter that is currently being played back. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::availableTitles() const - - Returns the number of titles that the current media source - contains. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentTitle() const - - Returns the title that is currently played back. - - The current title is 0 (the first) by default. - - \sa Feature -*/ - -/*! - \fn bool Phonon::MediaController::autoplayTitles() const - - Returns true if titles will automatically be played when the media - is played; otherwise returns false. - - The media controller will play the titles of the media source in - sequence when the media object's \l{Phonon::MediaObject::}{play()} - function is called. If the autoplay option is disabled, the media - object will play the - \l{Phonon::}{MediaController::currentTitle()}{current title} and then - finish the playback. - - \sa setAutoplayTitles(), currentTitle() -*/ - -/*! - \fn void Phonon::MediaController::setAutoplayTitles(bool enable) - - Sets the titles to play automatically when the media is played if - \a enable is true; otherwise disables this option. - - The media controller will play the titles of the media source in - sequence when the media object's \l{Phonon::MediaObject::}{play()} - function is called. If the autoplay option is disabled, the media - object will play the - \l{Phonon::}{MediaController::currentTitle()}{current title} and then - finish the playback. - - \sa autoplayTitles(), currentTitle() -*/ - -/*! - \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) - - Sets the current angle to the given \a angleNumber if the media - file or device supports navigation by angle number. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) - - Sets the current chapter to the given \a chapterNumber if the media - file or device supports navigation by chapter number. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) - - Skips to the given title \a titleNumber. - - If it was playing before the title change it will start playback on the new title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::nextTitle() - - Skips to the next title. - - If it was playing before the title change it will start playback on the next title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::previousTitle() - - Skips to the previous title. - - If it was playing before the title change it will start playback on the previous title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) - - This signal is emitted whenever the number of available angles changes. - The new number of available angles is given by \a availableAngles. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::angleChanged(int angleNumber) - - This signal is emitted whenever the current angle changes. - The new angle number is given by \a angleNumber. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) - - This signal is emitted whenever the number of available chapters changes. - The new number of available chapters is given by \a availableChapters. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::chapterChanged(int chapterNumber) - - This signal is emitted whenever the current chapter changes. - The new chapter number is given by \a chapterNumber. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) - - This signal is emitted whenever the number of available titles changes. - The new number of available titles is given by \a availableTitles. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::titleChanged(int titleNumber) - - This signal is emitted whenever the current title changes. - The new title number is given by \a titleNumber. - - \sa Feature -*/ - -/*! - \class Phonon::VideoWidget - \inmodule Phonon - \inheaderfile Phonon/VideoWidget - \since 4.4 - \ingroup advanced - \ingroup multimedia - \brief The VideoWidget class provides a widget that is used to display video. - - The VideoWidget class renders the video of a media stream on a - QWidget. It is connected to the \l{Phonon::}{MediaObject}, of - which video stream it should render. You connect the two objects - using the Phonon::createPath() function. - - The widget has some possibilities to manipulate the video - stream. You can change the brightness(), hue(), saturation(), - and contrast(). - - Resizing of the video is handled automatically, but you can affect - the way the video is resized with the aspectRatio and scaleMode - properties. By default, the widget will use the aspect ratio of - the video stream itself. - - The video widget takes the size of the video when it receives a new video - stream (i.e., when a new MediaSource is set on the MediaObject to which it is - connected). If you need to know the size of the video, you can call - \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the - MediaObject leaves the \l{Phonon::}{LoadingState}). - - It is also possible to go to \l{fullScreen}{full screen} mode. - - A typical example of usage follows below: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 - - \sa {Phonon Module} -*/ - -/*! - \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) - - Constructs a new video widget with the specified \a parent. -*/ - -/*! - \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) - \internal - - Constructs a new video widget with the specified \a parent. -*/ - -/*! - \fn bool Phonon::VideoWidget::event(QEvent *) - \reimp -*/ - -/*! - \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) - \reimp -*/ - -/*! - \enum Phonon::VideoWidget::ScaleMode - - The ScaleMode enum describes how to treat aspect ratio during - resizing of video. - - \value FitInView The video will be fitted to fill the view - keeping aspect ratio. - \value ScaleAndCrop The video is scaled -*/ - -/*! - \property Phonon::VideoWidget::fullScreen - This property holds whether the video is shown using the complete - screen. - - The property differs from QWidget::fullScreen in that it is - writeable. - - By default the widget is not shown in fullScreen. - - \warning When switching to full screen mode using setFullScreen(), - the widget onto which the video is rendered is shown as a - top-level window. Key event forwarding is handled by VideoWidget, - but if you need to handle other events, e.g., mouse events, you - should handle fullscreen mode yourself. -*/ - -/*! - \property Phonon::VideoWidget::aspectRatio - Defaults to AspectRatioAuto. - - \sa AspectRatio -*/ - -/*! - \property Phonon::VideoWidget::scaleMode - - If the size of the widget and the size of the video are not equal. - The video will be zoomed to fit the widget. The smaller zoom - (AddBarsScaleMode) adds black bars at the left/right or top/bottom to - make all of the image visible (default). The bigger zoom (ExpandMode) - fills the widget completely, keeping all information in one direction - and leaving parts of the image outside of the widget in the other - direction. -*/ - -/*! - \property Phonon::VideoWidget::brightness - - This property holds brightness of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::contrast - - This property holds the contrast of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::hue - - This property holds the hue of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::saturation - - This property holds saturation of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \enum Phonon::VideoWidget::AspectRatio - - Defines the width:height to be used for the video. - - \value AspectRatioAuto - Let the decoder find the aspect ratio automatically from the - media file (this is the default). - - \value AspectRatioWidget - Fits the video into the widget making the aspect ratio depend - solely on the size of the widget. This way the aspect ratio - is freely resizeable by the user. - - \value AspectRatio4_3 - Make width/height == 4/3, which is the old TV size and - monitor size (1024/768 == 4/3). (4:3) - - \value AspectRatio16_9 - Make width/height == 16/9, which is the size of most current - media. (16:9) -*/ - -/*! - \fn void Phonon::VideoWidget::exitFullScreen() - - Convenience slot, calling setFullScreen(false) -*/ - - -/*! - \fn void Phonon::VideoWidget::enterFullScreen() - - Convenience slot, calling setFullScreen(true) -*/ - -/*! - \class Phonon::VideoWidgetInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() -*/ - -/*! - \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 - \internal -*/ - -/*! - \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 - \internal -*/ - -/*! - \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 - \internal -*/ - -/*! - \class Phonon::PlatformPlugin - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 - - Creates a AbstractMediaStream object with the given \a parent that provides the data - for the given URL specified by \a url. - \omit - On KDE this uses KIO. - \endomit -*/ - -/*! - \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 - - Returns the icon for the given icon name. -*/ - -/*! - \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, - const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 - - Shows a notification pop-up with the given \a notificationName and \a text. - Each action in the associated list of \a actions is connected to the \a actionSlot - of the specified \a receiver object, which is expected to act on the actions as - they are triggered by the user. -*/ - -/*! - \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 - - Returns the name of the application. For most Qt application this is - QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. -*/ - - -/*! - \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 - - Creates a backend object. This way the platform can decide the backend preference. -*/ - -/*! - \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 - - Using the library loader of the platform, loads a given backend provided the - specified \a library and \a version. -*/ - -/*! - \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 - - Tries to check whether the default backend supports the MIME type specified by \a mimeType - without loading the actual backend library. - \omit - On KDE this reads the MIME type list from the .desktop file of - the backend. - \endomit -*/ - -/*! - \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 - - Saves the volume for the given output. -*/ - -/*! - \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 - - Loads the volume for the given output. -*/ - -/*! - \class Phonon::MediaNode - \inmodule Phonon - \inheaderfile Phonon/MediaNode - \since 4.4 - \brief The MediaNode class is the base class for all nodes in a media graph. - - In all phonon applications, one builds a media graph consisting of - MediaNodes. The graph will take multimedia content, e.g., from a - file, as input. After its nodes have processed the multimedia, the - graph will output the media again, e.g., to a sound card. - - The multimedia content is streamed over \l{Phonon::}{Path}s - between the nodes in the graph. You can query the paths that are - connected to a media node with inputPaths() and outputPaths(). - - You can check whether the node is implemented by the current - backend by calling isValid(). This does not guarantee that an - instance of the class works as expected, but that the backend has - implemented functionality for the class. - - Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, - \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. - Please refer to their class descriptions for details about their usage, and to - find out which nodes can be connected to each other. See also \l{Building - Graphs} in Phonon's \l{Phonon Overview}{overview} document. - - Two nodes are connected to each other using the - Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} - functions (only \l{Phonon::Effect}s use - \l{Phonon::Path::}{insertEffect()}). We show a code example below, - in which we build a media graph for video playback and then query - its media nodes for their \l{Phonon::}{Path}s: - - \snippet doc/src/snippets/medianodesnippet.cpp 0 - - When you create a Phonon application, you will likely build the - graph yourself. This makes isValid() the most useful function of - this class. The other two functions help navigate the graph, which - you do not need to do as you created the nodes yourself. - - \sa {Phonon Overview}, Phonon::MediaObject, - Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} -*/ - -/*! - \fn virtual Phonon::MediaNode::~MediaNode() - - Destroys the media node and any paths connecting it to other - nodes. Any \l{Phonon::}{Effect}s connected to these paths will - also be deleted. -*/ - -/*! - \fn bool Phonon::MediaNode::isValid() const - - Returns true if the backend provides an implementation of this - class; otherwise returns false. - - This does not guarantee that instances of the class works as - expected, but that the backend has implemented the functionality - for this class. For instance, Qt's GStreamer backend will return - true for instances of the \l{Phonon::}{AudioOutput} class, even if - there is a problem with GStreamer and it could not play sound. - -*/ - -/*! - \fn QList Phonon::MediaNode::inputPaths() const - - Returns the paths that inputs multimedia to this media node. - - \sa outputPaths() -*/ - -/*! - \fn QList Phonon::MediaNode::outputPaths() const - - Returns the paths to which this media node outputs media. - - \sa inputPaths() -*/ - -/*! - \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) - \internal -*/ - -/*! - \class Phonon::GlobalConfig - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn Phonon::GlobalConfig::GlobalConfig() - \internal -*/ - -/*! - \fn Phonon::GlobalConfig::~GlobalConfig() - \internal -*/ - -/*! - \fn QList Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const - \internal -*/ - -/*! - \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const - \internal -*/ - -/*! - \class Phonon::ObjectDescriptionData - \inmodule Phonon - \since 4.4 - \internal - \brief Data class for objects describing devices or features of the backend. - - \sa Phonon::BackendCapabilities -*/ - -/*! - \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const - - Returns \c true if this ObjectDescription describes the same - as \a otherDescription; otherwise returns \c false. -*/ - -/*! - \fn QString Phonon::ObjectDescriptionData::name() const - - Returns the name of the capture source. - - \return A string that should be presented to the user to - choose the capture source. -*/ - -/*! - \fn QString Phonon::ObjectDescriptionData::description() const - - Returns a description of the capture source. This text should - make clear what sound source this is, which is sometimes hard - to describe or understand from just the name. - - \return A string describing the capture source. -*/ - -/*! - \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const - - Returns a named property. - - If the property is not set an invalid value is returned. - - \sa propertyNames() -*/ - -/*! - \fn QList Phonon::ObjectDescriptionData::propertyNames() const - - Returns all names that return valid data when property() is called. - - \sa property() -*/ - -/*! - \fn bool Phonon::ObjectDescriptionData::isValid() const - - Returns true if the Tuple is valid (index != -1); otherwise returns - false. -*/ - -/*! - \fn int Phonon::ObjectDescriptionData::index() const - - A unique identifier for this device/. Used internally - to distinguish between the devices/. - - \return An integer that uniquely identifies every device. -*/ - -/*! - \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) - \internal -*/ - -/*! - \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() - \internal -*/ - -/*! - \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) - \internal -*/ - -/*! - \class Phonon::AddonInterface - \inmodule Phonon - \since 4.4 - \internal - \brief Interface for Menu, Chapter, Angle and Title/Track control. -*/ - -/*! - \fn virtual Phonon::AddonInterface::~AddonInterface() - \internal -*/ - -/*! - \enum Phonon::AddonInterface::Interface - - This enum describes the type of interface represented by an AddonInterface object. - - \value NavigationInterface - \value ChapterInterface - \value AngleInterface - \value TitleInterface -*/ - -/*! - \enum Phonon::AddonInterface::NavigationCommand - \internal - \value Menu1Button -*/ - -/*! - \enum Phonon::AddonInterface::ChapterCommand - \internal - \value availableChapters - \value chapter - \value setChapter -*/ - -/*! - \enum Phonon::AddonInterface::AngleCommand - \internal - \value availableAngles - \value angle - \value setAngle -*/ - -/*! - \enum Phonon::AddonInterface::TitleCommand - \internal - \value availableTitles - \value title - \value setTitle - \value autoplayTitles - \value setAutoplayTitles -*/ - -/*! - \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 - \internal -*/ - -/*! - \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, - const QList &arguments) = 0 - \internal -*/ - -/*! - \class Phonon::MediaNodePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \namespace Phonon::Factory - \inmodule Phonon - \internal -*/ - -/*! - \fn Sender *Phonon::Factory::sender() - - Returns a pointer to the object emitting the signals. - - \sa Sender::backendChanged() -*/ - -/*! - \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) - - Create a new backend object for a MediaObject. - - \return a pointer to the MediaObject the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) - - Create a new backend object for a Effect. - - \return a pointer to the Effect the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) - - Create a new backend object for a VolumeFaderEffect. - - \return a pointer to the VolumeFaderEffect the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) - - Create a new backend object for a AudioOutput. - - \return a pointer to the AudioOutput the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) - - Create a new backend object for a VideoWidget. - - \return a pointer to the VideoWidget the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) - - \return a pointer to the backend interface. -*/ - -/*! - \fn QString Phonon::Factory::identifier() - - Unique identifier for the Backend. Can be used in configuration files - for example. -*/ - - -/*! - \fn QString Phonon::Factory::backendName() - - Get the name of the Backend. - \omit - It's the name from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendComment() - - Get the comment of the Backend. - \omit - It's the comment from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendVersion() - - Get the version of the Backend. - \omit - It's the version from the .desktop file. - \endomit - - The version is especially interesting if there are several versions - available for binary incompatible versions of the backend's media - framework. -*/ - -/*! - \fn QString Phonon::Factory::backendIcon() - - Get the icon (name) of the Backend. - \omit - It's the icon from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendWebsite() - - Get the website of the Backend. - \omit - It's the website from the .desktop file. - \endomit -*/ - -/*! - \fn QObject *Phonon::Factory::registerQObject(QObject *object) - - Registers the given backend \a object with the factory. -*/ - -/*! - \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) -*/ - -/*! - \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) - \internal -*/ - -/*! - \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) - \internal -*/ - -/*! - \fn void Phonon::Factory::setBackend(QObject *) -*/ - -/*! - \fn PlatformPlugin *Phonon::Factory::platformPlugin() -*/ - -/*! -/*! - \class Phonon::AbstractMediaStreamPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::FrontendInterfacePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectWidgetPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::IODeviceStream - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) - \internal - - Creates a new IODeviceStream with the given \a ioDevice and \a - parent. - -*/ - -/*! - \fn Phonon::IODeviceStream::~IODeviceStream() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::reset() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::needData() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::seekStream(qint64) - \internal -*/ - -/*! - \namespace Phonon::Platform - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::EffectDescriptionModel - \inmodule Phonon - \brief provides a item view model containing available audio effects. - -*/ - -/*! - \typedef Phonon::SubtitleDescription - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::SubtitleDescriptionModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioChannelDescription - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioChannelDescriptionModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioCaptureDevice - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioCaptureDeviceModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::CleanUpFunction - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::QObjectPair - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \typedef Phonon::AudioOutputDeviceModel - \inmodule Phonon - \brief provides an item view model containing available audio output devices. - -*/ - -/*! - \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) - \internal - -*/ - -/*! - \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() - \internal -*/ - -/*! - \class Phonon::ConstIface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::CleanUpGlobalStatic - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectParameterPrivate - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::QSettingsGroup - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::MediaNodeDestructionHandler - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() - \internal - Called from Base::~Base if this object was registered - using BasePrivate::addDestructionHandler(). -*/ - -/*! - \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) - \internal -*/ - -/*! - \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) - \internal - - Constructs a new EffectWidget for the specified \a effect and with - the specified \a parent. -*/ - -/*! - \fn Phonon::EffectWidget::~EffectWidget() - \internal -*/ - -/*! - \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription &o) - \internal -*/ - -/*! - \class Phonon::ListModelHelper - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class AudioOutputInterface42 - \inmodule Phonon - \since 4.4 - \internal -*/ - diff --git a/doc/src/q3asciicache.qdoc b/doc/src/q3asciicache.qdoc deleted file mode 100644 index 43537cc..0000000 --- a/doc/src/q3asciicache.qdoc +++ /dev/null @@ -1,465 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3AsciiCache - \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. - \compat - - Q3AsciiCache is implemented as a template class. Define a template - instance Q3AsciiCache\ to create a cache that operates on - pointers to X (X*). - - A cache is a least recently used (LRU) list of cache items. The - cache items are accessed via \c char* keys. For Unicode keys use - the Q3Cache template instead, which uses QString keys. A Q3Cache - has the same performace as a Q3AsciiCache. - - Each cache item has a cost. The sum of item costs, totalCost(), - will not exceed the maximum cache cost, maxCost(). If inserting a - new item would cause the total cost to exceed the maximum cost, - the least recently used items in the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink tells the cache to delete items that - are removed. The default is to not delete items when then are - removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item the virtual function - Q3PtrCollection::deleteItem() is called. Its default implementation - in Q3AsciiCache is to delete the item if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - There is a Q3AsciiCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache -*/ - -/*! - \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison only affects the 26 letters in - US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes - a copy of the cache keys, otherwise it copies just the const char - * pointer - slightly faster if you can guarantee that the keys - will never change, but very risky. -*/ - -/*! - \fn Q3AsciiCache::~Q3AsciiCache() - - Removes all items from the cache and destroys it. - All iterators that access this cache will be reset. -*/ - -/*! - \fn Q3AsciiCache& Q3AsciiCache::operator=( const Q3AsciiCache &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3AsciiCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3AsciiCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3AsciiCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3AsciiCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() size() -*/ - -/*! - \fn uint Q3AsciiCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3AsciiCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) - - Inserts the item \a d into the cache using key \a k, and with an - associated cost of \a c. Returns TRUE if the item is successfully - inserted. Returns FALSE if the item is not inserted, for example, - if the cost of the item exceeds maxCost(). - - The cache's size is limited, and if the total cost is too high, - Q3AsciiCache will remove old, least recently used items until there - is room for this new item. - - Items with duplicate keys can be inserted. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE, you must delete \a d - yourself. Additionally, be very careful about using \a d after - calling this function, because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3AsciiCache::remove( const char *k ) - - Removes the item with key \a k and returns TRUE if the item was - present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink. - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3AsciiCache::take( const char *k ) - - Takes the item associated with \a k out of the cache without - deleting it and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3AsciiCache::clear() - - Removes all items from the cache, and deletes them if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been - enabled. - - All cache iterators that operate on this cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3AsciiCache::find( const char *k, bool ref ) const - - Returns the item with key \a k, or 0 if the key does not exist - in the cache. If \a ref is TRUE (the default), the item is moved - to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3AsciiCache::operator[]( const char *k ) const - - Returns the item with key \a k, or 0 if \a k does not exist in - the cache, and moves the item to the front of the least recently - used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3AsciiCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3AsciiCacheIterator - \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators - that refer an item when that item is removed. - - Q3AsciiCacheIterator provides an operator++() and an operator+=() - to traverse the cache; current() and currentKey() to access the - current cache item and its key. It also provides atFirst() and - atLast(), which return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty; and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3AsciiCache -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current() but moves - independently from there on. -*/ - -/*! - \fn Q3AsciiCacheIterator& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3AsciiCacheIterator::count() const - - Returns the number of items in the cache over which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3AsciiCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 - if it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes that the new current item for the iterator. If - current() was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/q3asciidict.qdoc b/doc/src/q3asciidict.qdoc deleted file mode 100644 index 9a51db1..0000000 --- a/doc/src/q3asciidict.qdoc +++ /dev/null @@ -1,416 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3AsciiDict - \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. - \compat - - Q3AsciiDict is implemented as a template class. Define a template - instance Q3AsciiDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - char* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template - instead, which uses QString keys. A Q3Dict has the same - performace as a Q3AsciiDict. - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 - In this example we use a dictionary to keep track of the line - edits we're using. We insert each line edit into the dictionary - with a unique name and then access the line edits via the - dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number (a - bit larger than the expected number of entries). This makes the - hash distribution better and will improve lookup performance. - - When \a caseSensitive is TRUE (the default) Q3AsciiDict treats - "abc" and "Abc" as different keys; when it is FALSE "abc" and - "Abc" are the same. Case-insensitive comparison only considers the - 26 letters in US-ASCII. - - If \a copyKeys is TRUE (the default), the dictionary copies keys - using strcpy(); if it is FALSE, the dictionary just copies the - pointers. -*/ - -/*! - \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3AsciiDict::~Q3AsciiDict() - - Removes all items from the dictionary and destroys it. - - The items are deleted if auto-delete is enabled. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3AsciiDict &Q3AsciiDict::operator=(const Q3AsciiDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy) unless newItem() has been reimplemented(). -*/ - -/*! - \fn uint Q3AsciiDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3AsciiDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3AsciiDict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise it returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::insert( const char *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3AsciiDict::replace( const char *key, const type *item ) - - Replaces an item that has a key equal to \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3AsciiDict::remove( const char *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the key existed in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::take( const char *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3AsciiDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::find( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3AsciiDict::operator[]( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does - not exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3AsciiDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3AsciiDict::read( QDataStream &s, - Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3AsciiDictIterator - \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. - \compat - - Q3AsciiDictIterator is implemented as a template class. Define a - template instance Q3AsciiDictIterator\ to create a dictionary - iterator that operates on Q3AsciiDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 - In the example we insert some line edits into a dictionary, then - iterate over the dictionary printing the strings associated with - those line edits. - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. - - Multiple iterators may independently traverse the same dictionary. - A Q3AsciiDict knows about all the iterators that are operating on - the dictionary. When an item is removed from the dictionary, - Q3AsciiDict updates all the iterators that are referring to the - removed item to point to the next item in the (arbitrary) - traversal order. - - \sa Q3AsciiDict -*/ - -/*! - \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3AsciiDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0, - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3AsciiDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3AsciiDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiDictIterator::currentKey() const - - Returns a pointer to the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3cache.qdoc b/doc/src/q3cache.qdoc deleted file mode 100644 index d8799b6..0000000 --- a/doc/src/q3cache.qdoc +++ /dev/null @@ -1,461 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3Cache - \brief The Q3Cache class is a template class that provides a cache based on QString keys. - \compat - - A cache is a least recently used (LRU) list of cache items. Each - cache item has a key and a certain cost. The sum of item costs, - totalCost(), never exceeds the maximum cache cost, maxCost(). If - inserting a new item would cause the total cost to exceed the - maximum cost, the least recently used items in the cache are - removed. - - Q3Cache is a template class. Q3Cache\ defines a cache that - operates on pointers to X, or X*. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item, the virtual function - Q3PtrCollection::deleteItem() is called. The default - implementation deletes the item if auto-deletion is enabled, and - does nothing otherwise. - - There is a Q3CacheIterator that can be used to traverse the items - in the cache in arbitrary order. - - In Q3Cache, the cache items are accessed via QString keys, which - are Unicode strings. If you want to use non-Unicode, plain 8-bit - \c char* keys, use the Q3AsciiCache template. A Q3Cache has the - same performance as a Q3AsciiCache. - - \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache -*/ - -/*! - \fn Q3Cache::Q3Cache( const Q3Cache &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it a prime number and at least 50% bigger - than the largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison considers all Unicode letters. -*/ - -/*! - \fn Q3Cache::~Q3Cache() - - Removes all items from the cache and destroys it. All iterators - that access this cache will be reset. -*/ - -/*! - \fn Q3Cache& Q3Cache::operator=( const Q3Cache &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3Cache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3Cache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3Cache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are deleted - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3Cache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3Cache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3Cache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and associated - cost, \a c. Returns TRUE if it is successfully inserted; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3Cache will remove old, least recently used items until there is - room for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (which could happen, e.g. - if the cost of this item alone exceeds maxCost()) you must delete - \a d yourself. Additionally, be very careful about using \a d - after calling this function because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3Cache::remove( const QString &k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3Cache::take( const QString &k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3Cache::clear() - - Removes all items from the cache and deletes them if auto-deletion - has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3Cache::find( const QString &k, bool ref ) const - - Returns the item associated with key \a k, or 0 if the key does - not exist in the cache. If \a ref is TRUE (the default), the item - is moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3Cache::operator[]( const QString &k ) const - - Returns the item associated with key \a k, or 0 if \a k does not - exist in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3Cache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/***************************************************************************** - Q3CacheIterator documentation - *****************************************************************************/ - -/*! - \class Q3CacheIterator qcache.h - \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3Cache. Q3Cache updates all iterators that - refer an item when that item is removed. - - Q3CacheIterator provides an operator++(), and an operator+=() to - traverse the cache. The current() and currentKey() functions are - used to access the current cache item and its key. The atFirst() - and atLast() return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty, and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3Cache -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3CacheIterator& Q3CacheIterator::operator=( const Q3CacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3CacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3CacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - it returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3CacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3CacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3CacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3CacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3CacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3CacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn QString Q3CacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3CacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3CacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator++() - - Prefix++ makes the iterator point to the item just after current() - and makes that the new current item for the iterator. If current() - was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3CacheIterator::operator--() - - Prefix-- makes the iterator point to the item just before - current() and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/q3dict.qdoc b/doc/src/q3dict.qdoc deleted file mode 100644 index 0e6d51d..0000000 --- a/doc/src/q3dict.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3Dict - \brief The Q3Dict class is a template class that provides a - dictionary based on QString keys. - \compat - - Q3Dict is implemented as a template class. Define a template - instance Q3Dict\ to create a dictionary that operates on - pointers to X (X *). - - A dictionary is a collection of key-value pairs. The key is a - QString used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - If you want to use non-Unicode, plain 8-bit \c char* keys, use the - Q3AsciiDict template. A Q3Dict has the same performance as a - Q3AsciiDict. If you want to have a dictionary that maps QStrings to - QStrings use QMap. - - The size() of the dictionary is very important. In order to get - good performance, you should use a suitably large prime number. - Suitable means equal to or larger than the maximum expected number - of dictionary items. Size is set in the constructor but may be - changed with resize(). - - Items are inserted with insert(); 0 pointers cannot be inserted. - Items are removed with remove(). All the items in a dictionary can - be removed with clear(). The number of items in the dictionary is - returned by count(). If the dictionary contains no items isEmpty() - returns TRUE. You can change an item's value with replace(). Items - are looked up with operator[](), or with find() which return a - pointer to the value or 0 if the given key does not exist. You can - take an item out of the dictionary with take(). - - Calling setAutoDelete(TRUE) for a dictionary tells it to delete - items that are removed. The default behavior is not to delete - items when they are removed. - - When an item is inserted, the key is converted (hashed) to an - integer index into an internal hash array. This makes lookup very - fast. - - Items with equal keys are allowed. When inserting two items with - the same key, only the last inserted item will be accessible (last - in, first out) until it is removed. - - The Q3DictIterator class can traverse the dictionary, but only in - an arbitrary order. Multiple iterators may independently traverse - the same dictionary. - - When inserting an item into a dictionary, only the pointer is - copied, not the item itself, i.e. a shallow copy is made. It is - possible to make the dictionary copy all of the item's data (a - deep copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a dictionary item, the virtual function - Q3PtrCollection::deleteItem() is called. Q3Dict's default - implementation is to delete the item if auto-deletion is enabled. - - \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number - (e.g. a prime that's slightly larger than the expected number of - entries). This makes the hash distribution better which will lead - to faster lookup. - - If \a caseSensitive is TRUE (the default), keys which differ only - by case are considered different. -*/ - -/*! - \fn Q3Dict::Q3Dict( const Q3Dict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3Dict::~Q3Dict() - - Removes all items from the dictionary and destroys it. If - setAutoDelete() is TRUE, each value is deleted. All iterators that - access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3Dict &Q3Dict::operator=(const Q3Dict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared, then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3Dict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3Dict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3Dict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3Dict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3Dict::insert( const QString &key, const type *item ) - - Inserts the key \a key with value \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3Dict::replace( const QString &key, const type *item ) - - Replaces the value of the key, \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 - - If there are two or more items with equal keys, then the last item - that was inserted will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3Dict::remove( const QString &key ) - - Removes the item with \a key from the dictionary. Returns TRUE if - successful, i.e. if the item is in the dictionary; otherwise - returns FALSE. - - If there are two or more items with equal keys, then the last item - that was inserted will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::take( const QString &key ) - - Takes the item with \a key out of the dictionary without deleting - it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the last item - that was inserted will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3Dict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on the dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::find( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not exist - in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3Dict::operator[]( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3Dict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3DictIterator - \brief The Q3DictIterator class provides an iterator for Q3Dict collections. - \compat - - Q3DictIterator is implemented as a template class. Define a - template instance Q3DictIterator\ to create a dictionary - iterator that operates on Q3Dict\ (dictionary of X*). - - The traversal order is arbitrary; when we speak of the "first", - "last" and "next" item we are talking in terms of this arbitrary - order. - - Multiple iterators may independently traverse the same dictionary. - A Q3Dict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3Dict - updates all iterators that are referring to the removed item to - point to the next item in the (arbitrary) traversal order. - - Example: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 - In the example we insert some pointers to line edits into a - dictionary, then iterate over the dictionary printing the strings - associated with the line edits. - - \sa Q3Dict -*/ - -/*! - \fn Q3DictIterator::Q3DictIterator( const Q3Dict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the first item in the dictionary, \a dict. First - in this context means first in the arbitrary traversal order. -*/ - -/*! - \fn Q3DictIterator::~Q3DictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3DictIterator::count() const - - Returns the number of items in the dictionary over which the - iterator is operating. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3DictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3DictIterator::toFirst() - - Resets the iterator, making the first item the first current item. - First in this context means first in the arbitrary traversal - order. Returns a pointer to this item. - - If the dictionary is empty it sets the current item to 0 and - returns 0. -*/ - -/*! - \fn type *Q3DictIterator::operator*() - \internal -*/ - -/*! - \fn Q3DictIterator::operator type*() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - - -/*! - \fn type *Q3DictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn QString Q3DictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3DictIterator::operator()() - - Makes the next item current and returns the original current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator++() - - Prefix ++ makes the next item current and returns the new current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator+=( uint jump ) - \internal - Sets the current item to the item \a jump positions after the current item, - and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is empty, - it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3intcache.qdoc b/doc/src/q3intcache.qdoc deleted file mode 100644 index dfff679..0000000 --- a/doc/src/q3intcache.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3IntCache - \brief The Q3IntCache class is a template class that provides a cache based on long keys. - \compat - - Q3IntCache is implemented as a template class. Define a template - instance Q3IntCache\ to create a cache that operates on - pointers to X, or X*. - - A cache is a least recently used (LRU) list of cache items, - accessed via \c long keys. Each cache item has a cost. The sum - of item costs, totalCost(), will not exceed the maximum cache - cost, maxCost(). If inserting a new item would cause the total - cost to exceed the maximum cost, the least recently used items in - the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e. remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a cache item, the item will be automatically - deleted if auto-deletion is enabled. - - There is a Q3IntCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache -*/ - -/*! - \fn Q3IntCache::Q3IntCache( const Q3IntCache &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn Q3IntCache::Q3IntCache( int maxCost, int size ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item is associated with a cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. -*/ - -/*! - \fn Q3IntCache::~Q3IntCache() - - Removes all items from the cache and then destroys the int cache. - If auto-deletion is enabled the cache's items are deleted. All - iterators that access this cache will be reset. -*/ - -/*! - \fn Q3IntCache& Q3IntCache::operator=( const Q3IntCache &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3IntCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3IntCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3IntCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3IntCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3IntCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit larger than count() is likely to be. -*/ - -/*! - \fn bool Q3IntCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and assigns it - a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3IntCache will remove old, least-used items until there is room - for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (for example, the cost \c, - exceeds maxCost()), you must delete \a d yourself. Additionally, - be very careful about using \a d after calling this function. Any - other insertions into the cache, from anywhere in the application - or within Qt itself, could cause the object to be discarded from - the cache and the pointer to become invalid. -*/ - -/*! - \fn bool Q3IntCache::remove( long k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e. if you - have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted most recently is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type * Q3IntCache::take( long k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out or 0 if - the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted most recently is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3IntCache::clear() - - Removes all items from the cache, and deletes them if - auto-deletion has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type * Q3IntCache::find( long k, bool ref ) const - - Returns the item associated with \a k, or 0 if the key does not - exist in the cache. If \a ref is TRUE (the default), the item is - moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. -*/ - -/*! - \fn type * Q3IntCache::operator[]( long k ) const - - Returns the item associated with \a k, or 0 if \a k does not exist - in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3IntCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3IntCacheIterator - \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3IntCache. Q3IntCache updates all iterators - that refer an item when that item is removed. - - Q3IntCacheIterator provides an operator++(), and an operator+=() to - traverse the cache; current() and currentKey() to access the - current cache item and its key; atFirst() atLast(), which return - TRUE if the iterator points to the first/last item in the cache; - isEmpty(), which returns TRUE if the cache is empty; and count(), - which returns the number of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3IntCache -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache (or rather, the - first item is defined to be the item at which this constructor - sets the iterator to point). -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3IntCacheIterator& Q3IntCacheIterator::operator=( const Q3IntCacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3IntCacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3IntCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3IntCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3IntCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3IntCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3IntCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes it the new current item for the iterator. If - current() was the last item, operator--() returns 0. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes it the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ diff --git a/doc/src/q3intdict.qdoc b/doc/src/q3intdict.qdoc deleted file mode 100644 index cef2e79..0000000 --- a/doc/src/q3intdict.qdoc +++ /dev/null @@ -1,390 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3IntDict - \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ - \compat - - Q3IntDict is implemented as a template class. Define a template - instance Q3IntDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is an \c - long used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict -*/ - - -/*! - \fn Q3IntDict::Q3IntDict( int size ) - - Constructs a dictionary using an internal hash array of size \a - size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better which leads to faster lookup. -*/ - -/*! - \fn Q3IntDict::Q3IntDict( const Q3IntDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3IntDict::~Q3IntDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3IntDict &Q3IntDict::operator=(const Q3IntDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3IntDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3IntDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3IntDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3IntDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3IntDict::insert( long key, const type *item ) - - Insert item \a item into the dictionary using key \a key. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3IntDict::replace( long key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3IntDict::remove( long key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the \a key is in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal - order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::take( long key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary's traversing order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3IntDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::find( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3IntDict::operator[]( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3IntDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3IntDictIterator - \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. - \compat - - Q3IntDictIterator is implemented as a template class. Define a - template instance Q3IntDictIterator\ to create a dictionary - iterator that operates on Q3IntDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 - - Note that the traversal order is arbitrary; you are not guaranteed the - order shown above. - - Multiple iterators may independently traverse the same dictionary. - A Q3IntDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3IntDict - updates all iterators that refer the removed item to point to the - next item in the traversal order. - - \sa Q3IntDict -*/ - -/*! - \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the 'first' item in the \a dict. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. -*/ - -/*! - \fn Q3IntDictIterator::~Q3IntDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3IntDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise eturns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3IntDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. If the dictionary is empty it sets the current item to - 0 and returns 0. -*/ - -/*! - \fn Q3IntDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntDictIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3memarray.qdoc b/doc/src/q3memarray.qdoc deleted file mode 100644 index b9c1f73..0000000 --- a/doc/src/q3memarray.qdoc +++ /dev/null @@ -1,523 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3MemArray - \brief The Q3MemArray class is a template class that provides arrays of simple types. - \compat - - Q3MemArray is implemented as a template class. Define a template - instance Q3MemArray\ to create an array that contains X items. - - Q3MemArray stores the array elements directly in the array. It can - only deal with simple types (i.e. C++ types, structs, and classes - that have no constructors, destructors, or virtual functions). - Q3MemArray uses bitwise operations to copy and compare array - elements. - - The Q3PtrVector collection class is also a kind of array. Like most - old Qt collection classes, it uses pointers to the contained items. - - Q3MemArray uses explicit sharing with a - reference count. If more than one array shares common data and one - of the arrays is modified, all the arrays are modified. - - The benefit of sharing is that a program does not need to duplicate - data when it is not required, which results in lower memory use - and less copying of data. - - Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 - - Note concerning the use of Q3MemArray for manipulating structs or - classes: Compilers will often pad the size of structs of odd sizes - up to the nearest word boundary. This will then be the size - Q3MemArray will use for its bitwise element comparisons. Because - the remaining bytes will typically be uninitialized, this can - cause find() etc. to fail to find the element. Example: - - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 - - To work around this, make sure that you use a struct where - sizeof() returns the same as the sum of the sizes of the members - either by changing the types of the struct members or by adding - dummy members. - - Q3MemArray data can be traversed by iterators (see begin() and - end()). The number of items is returned by count(). The array can - be resized with resize() and filled using fill(). - - You can make a shallow copy of the array with assign() (or - operator=()) and a deep copy with duplicate(). - - Search for values in the array with find() and contains(). For - sorted arrays (see sort()) you can search using bsearch(). - - You can set the data directly using setRawData() and - resetRawData(), although this requires care. -*/ - -/*! \fn Q3MemArray::operator QVector() const - - Automatically converts the Q3MemArray into a QVector. -*/ - -/*! \typedef Q3MemArray::Iterator - A Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ConstIterator - A const Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ValueType - \internal -*/ - -/*! - \fn Q3MemArray::Q3MemArray() - - Constructs a null array. - - \sa isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( int size ) - - Constructs an array with room for \a size elements. Makes a null - array if \a size == 0. - - The elements are left uninitialized. - - \sa resize(), isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( const Q3MemArray &a ) - - Constructs a shallow copy of \a a. - - \sa assign() -*/ - -/*! - \fn Q3MemArray::Q3MemArray(const QVector &vector) - - Constructs a copy of \a vector. -*/ - -/*! - \fn Q3MemArray::Q3MemArray(int arg1, int arg2) - - Constructs an array \e{without allocating} array space. The - arguments \a arg1 and \a arg2 should be zero. Use at your own - risk. -*/ - -/*! - \fn Q3MemArray::~Q3MemArray() - - Dereferences the array data and deletes it if this was the last - reference. -*/ - -/*! - \fn Q3MemArray &Q3MemArray::operator=( const Q3MemArray &a ) - - Assigns a shallow copy of \a a to this array and returns a - reference to this array. - - Equivalent to assign( a ). -*/ - -/*! - \fn type *Q3MemArray::data() const - - Returns a pointer to the actual array data. - - The array is a null array if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3MemArray::nrefs() const - - Returns the reference count for the shared array data. This - reference count is always greater than zero. -*/ - -/*! - \fn uint Q3MemArray::size() const - - Returns the size of the array (maximum number of elements). - - The array is a null array if size() == 0. - - \sa isNull(), resize() -*/ - -/*! - \fn uint Q3MemArray::count() const - - Returns the same as size(). - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::isEmpty() const - - Returns TRUE if the array is empty; otherwise returns FALSE. - - isEmpty() is equivalent to isNull() for Q3MemArray (unlike - QString). -*/ - -/*! - \fn bool Q3MemArray::isNull() const - - Returns TRUE if the array is null; otherwise returns FALSE. - - A null array has size() == 0 and data() == 0. -*/ - -/*! - \fn bool Q3MemArray::resize( uint size, Optimization optim ) - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, or FALSE if the memory cannot be - allocated. - - New elements are not initialized. - - \a optim is either Q3GArray::MemOptim (the default) or - Q3GArray::SpeedOptim. When optimizing for speed rather than memory - consumption, the array uses a smart grow and shrink algorithm that - might allocate more memory than is actually needed for \a size - elements. This speeds up subsequent resize operations, for example - when appending many elements to an array, since the space has - already been allocated. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::resize( uint size ) - - \overload - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - New elements are not initialized. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::truncate( uint pos ) - - Truncates the array at position \a pos. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - Equivalent to resize(\a pos). - - \sa resize() -*/ - -/*! - \fn bool Q3MemArray::fill( const type &v, int size ) - - Fills the array with the value \a v. If \a size is specified as - different from -1, then the array will be resized before being - filled. - - Returns TRUE if successful, i.e. if \a size is -1, or \a size is - != -1 and the memory can be allocated; otherwise returns FALSE. - - \sa resize() -*/ - -/*! - \fn void Q3MemArray::detach() - - Detaches this array from shared array data; i.e. it makes a - private, deep copy of the data. - - Copying will be performed only if the \link nrefs() reference - count\endlink is greater than one. - - \sa copy() -*/ - -/*! - \fn Q3MemArray Q3MemArray::copy() const - - Returns a deep copy of this array. - - \sa detach(), duplicate() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::assign( const Q3MemArray &a ) - - Shallow copy. Dereferences the current array and references the - data contained in \a a instead. Returns a reference to this array. - - \sa operator=() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::assign( const type *data, uint size ) - - \overload - - Shallow copy. Dereferences the current array and references the - array data \a data, which contains \a size elements. Returns a - reference to this array. - - Do not delete \a data later; Q3MemArray will call free() on it - at the right time. -*/ - -/*! - \fn Q3MemArray &Q3MemArray::duplicate( const Q3MemArray &a ) - - Deep copy. Dereferences the current array and obtains a copy of - the data contained in \a a instead. Returns a reference to this - array. - - \sa copy() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::duplicate( const type *data, uint size ) - - \overload - - Deep copy. Dereferences the current array and obtains a copy of - the array data \a data instead. Returns a reference to this array. - The size of the array is given by \a size. - - \sa copy() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::setRawData( const type *data, uint size ) - - Sets raw data and returns a reference to the array. - - Dereferences the current array and sets the new array data to \a - data and the new array size to \a size. Do not attempt to resize - or re-assign the array data when raw data has been set. Call - resetRawData(\a data, \a size) to reset the array. - - Setting raw data is useful because it sets Q3MemArray data without - allocating memory or copying data. - - Example I (intended use): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 - - Example II (you don't want to do this): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 - - \warning If you do not call resetRawData(), Q3MemArray will attempt - to deallocate or reallocate the raw data, which might not be too - good. Be careful. - - \sa resetRawData() -*/ - -/*! - \fn void Q3MemArray::resetRawData( const type *data, uint size ) - - Removes internal references to the raw data that was set using - setRawData(). This means that Q3MemArray no longer has access to - the \a data, so you are free to manipulate \a data as you wish. - You can now use the Q3MemArray without affecting the original \a - data, for example by calling setRawData() with a pointer to some - other data. - - The arguments must be the \a data and length, \a size, that were - passed to setRawData(). This is for consistency checking. - - \sa setRawData() -*/ - -/*! - \fn int Q3MemArray::find( const type &v, uint index ) const - - Finds the first occurrence of \a v, starting at position \a index. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa contains() -*/ - -/*! - \fn int Q3MemArray::contains( const type &v ) const - - Returns the number of times \a v occurs in the array. - - \sa find() -*/ - -/*! - \fn void Q3MemArray::sort() - - Sorts the array elements in ascending order, using bitwise - comparison (memcmp()). - - \sa bsearch() -*/ - -/*! - \fn int Q3MemArray::bsearch( const type &v ) const - - In a sorted array (as sorted by sort()), finds the first - occurrence of \a v by using a binary search. For a sorted - array this is generally much faster than find(), which does - a linear search. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa sort(), find() -*/ - -/*! - \fn type &Q3MemArray::operator[]( int index ) const - - Returns a reference to the element at position \a index in the - array. - - This can be used to both read and set an element. Equivalent to - at(). - - \sa at() -*/ - -/*! - \fn type &Q3MemArray::at( uint index ) const - - Returns a reference to the element at position \a index in the array. - - This can be used to both read and set an element. - - \sa operator[]() -*/ - -/*! - \fn Q3MemArray::operator const type *() const - - Cast operator. Returns a pointer to the array. - - \sa data() -*/ - -/*! - \fn bool Q3MemArray::operator==( const Q3MemArray &a ) const - - Returns TRUE if this array is equal to \a a; otherwise returns - FALSE. - - The two arrays are compared bitwise. - - \sa operator!=() -*/ - -/*! - \fn bool Q3MemArray::operator!=( const Q3MemArray &a ) const - - Returns TRUE if this array is different from \a a; otherwise - returns FALSE. - - The two arrays are compared bitwise. - - \sa operator==() -*/ - -/*! - \fn Iterator Q3MemArray::begin() - - Returns an iterator pointing at the beginning of this array. This - iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn Iterator Q3MemArray::end() - - Returns an iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::begin() const - - \overload - - Returns a const iterator pointing at the beginning of this array. - This iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::end() const - - \overload - - Returns a const iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ diff --git a/doc/src/q3popupmenu.qdoc b/doc/src/q3popupmenu.qdoc deleted file mode 100644 index a2cfe08..0000000 --- a/doc/src/q3popupmenu.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PopupMenu - \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. - \compat - - Use QMenu in new applications. Note that the menu's actions must - be \l {Q3Action}s. -*/ - -/*! - \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) - - Constructs a menu with the given \a parent and \a name. -*/ - -/*! - \fn int Q3PopupMenu::exec() - - Pops up the menu and returns the ID of the action that was - selected. - - \sa QMenu::exec() -*/ - -/*! - \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) - - Pops up the menu at coordinate \a pos and returns the ID of the - action that was selected. - - If \a indexAtPoint is specified, the menu will pop up with the - item at index \a indexAtPoint under the mouse cursor. - - \sa QMenu::exec() -*/ diff --git a/doc/src/q3ptrdict.qdoc b/doc/src/q3ptrdict.qdoc deleted file mode 100644 index 38ca0bb..0000000 --- a/doc/src/q3ptrdict.qdoc +++ /dev/null @@ -1,388 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrDict - \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. - \compat - - Q3PtrDict is implemented as a template class. Define a template - instance Q3PtrDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - void* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 - In this example we use a dictionary to add an extra property (a - char*) to the line edits we're using. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict -*/ - - -/*! - \fn Q3PtrDict::Q3PtrDict( int size ) - - Constructs a dictionary using an internal hash array with the size - \a size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better and improves lookup performance. -*/ - -/*! - \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrDict::~Q3PtrDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrDict &Q3PtrDict::operator=(const Q3PtrDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into the dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3PtrDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3PtrDict::size() const - - Returns the size of the internal hash table (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3PtrDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::insert( void *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3PtrDict::replace( void *key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3PtrDict::remove( void *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if \a key is in the dictionary; - otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::take( void *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3PtrDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be - reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::find( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3PtrDict::operator[]( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3PtrDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3PtrDictIterator - \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. - \compat - - Q3PtrDictIterator is implemented as a template class. Define a - template instance Q3PtrDictIterator\ to create a dictionary - iterator that operates on Q3PtrDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 - In the example we insert some line edits into a dictionary, - associating a string with each. We then iterate over the - dictionary printing the associated strings. - - Multiple iterators may independently traverse the same dictionary. - A Q3PtrDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3PtrDict - updates all iterators that refer the removed item to point to the - next item in the traversing order. - - \sa Q3PtrDict -*/ - -/*! - \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3PtrDictIterator::~Q3PtrDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3PtrDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3PtrDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrDictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn void *Q3PtrDictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3ptrlist.qdoc b/doc/src/q3ptrlist.qdoc deleted file mode 100644 index 3000940..0000000 --- a/doc/src/q3ptrlist.qdoc +++ /dev/null @@ -1,1157 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrList - \brief The Q3PtrList class is a template class that provides a list. - \compat - - Q3ValueList is an STL-compatible alternative to this class. - - Define a template instance Q3PtrList\ to create a list that - operates on pointers to X (X*). - - The list class is indexable and has a \link at() current - index\endlink and a \link current() current item\endlink. The - first item corresponds to index position 0. The current index is - -1 if the current item is 0. - - Items are inserted with prepend(), insert() or append(). Items are - removed with remove(), removeRef(), removeFirst() and - removeLast(). You can search for an item using find(), findNext(), - findRef() or findNextRef(). The list can be sorted with sort(). - You can count the number of occurrences of an item with contains() - or containsRef(). You can get a pointer to the current item with - current(), to an item at a particular index position in the list - with at() or to the first or last item with getFirst() and - getLast(). You can also iterate over the list with first(), - last(), next() and prev() (which all update current()). The list's - deletion property is set with setAutoDelete(). - - \target example - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 - - Q3PtrList has several member functions for traversing the list, but - using a Q3PtrListIterator can be more practical. Multiple list - iterators may traverse the same list, independently of each other - and of the current list item. - - In the example above we make the call setAutoDelete(true). - Enabling auto-deletion tells the list to delete items that are - removed. The default is to not delete items when they are removed - but this would cause a memory leak in the example because there - are no other references to the list items. - - When inserting an item into a list only the pointer is copied, not - the item itself, i.e. a shallow copy. It is possible to make the - list copy all of the item's data (deep copy) when an item is - inserted. insert(), inSort() and append() call the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a list and reimplement newItem() to have deep copies. - - When removing an item from a list, the virtual function - Q3PtrCollection::deleteItem() is called. Q3PtrList's default - implementation is to delete the item if auto-deletion is enabled. - - The virtual function compareItems() can be reimplemented to - compare two list items. This function is called from all list - functions that need to compare list items, for instance - remove(const type*). If you only want to deal with pointers, there - are functions that compare pointers instead, for instance - removeRef(const type*). These functions are somewhat faster than - those that call compareItems(). - - List items are stored as \c void* in an internal Q3LNode, which - also holds pointers to the next and previous list items. The - functions currentNode(), removeNode(), and takeNode() operate - directly on the Q3LNode, but they should be used with care. The - data component of the node is available through Q3LNode::getData(). - - The Q3StrList class is a list of \c char*. - It reimplements newItem(), deleteItem() and compareItems(). (But - see QStringList for a list of Unicode QStrings.) - - \sa Q3PtrListIterator -*/ - - -/*! - \fn Q3PtrList::Q3PtrList() - - Constructs an empty list. -*/ - -/*! - \fn Q3PtrList::Q3PtrList( const Q3PtrList &list ) - - Constructs a copy of \a list. - - Each item in \a list is \link append() appended\endlink to this - list. Only the pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrList::~Q3PtrList() - - Removes all items from the list and destroys the list. - - All list iterators that access this list will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrList &Q3PtrList::operator=(const Q3PtrList &list) - - Assigns \a list to this list and returns a reference to this list. - - This list is first cleared and then each item in \a list is \link - append() appended\endlink to this list. Only the pointers are - copied (shallow copy) unless newItem() has been reimplemented. -*/ - -/*! - \fn bool Q3PtrList::operator==(const Q3PtrList &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - the same data; otherwise returns FALSE. -*/ - -/*! - \fn uint Q3PtrList::count() const - - Returns the number of items in the list. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrList::operator!=(const Q3PtrList &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - different data; otherwise returns FALSE. -*/ - - -/*! - \fn void Q3PtrList::sort() - - Sorts the list by the result of the virtual compareItems() - function. - - The heap sort algorithm is used for sorting. It sorts n items with - O(n*log n) comparisons. This is the asymptotic optimal solution of - the sorting problem. - - If the items in your list support operator<() and operator==(), - you might be better off with Q3SortedList because it implements the - compareItems() function for you using these two operators. - - \sa inSort() -*/ - -/*! - \fn bool Q3PtrList::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrList::insert( uint index, const type *item ) - - Inserts the \a item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is 0 to count() - (inclusively). The item is appended if \a index == count(). - - The inserted item becomes the current list item. - - \a item must not be 0. - - \sa append(), current(), replace() -*/ - -/*! - \fn bool Q3PtrList::replace( uint index, const type *item ) - - Replaces the item at position \a index with the new \a item. - - Returns TRUE if successful, i.e. \a index is in the range 0 to - count()-1. - - \sa append(), current(), insert() -*/ - -/*! - \fn void Q3PtrList::inSort( const type *item ) - - Inserts the \a item at its sorted position in the list. - - The sort order depends on the virtual compareItems() function. All - items must be inserted with inSort() to maintain the sorting - order. - - The inserted item becomes the current list item. - - \a item must not be 0. - - \warning Using inSort() is slow. An alternative, especially if you - have lots of items, is to simply append() or insert() them and - then use sort(). inSort() takes up to O(n) compares. That means - inserting n items in your list will need O(n^2) compares whereas - sort() only needs O(n*log n) for the same task. So use inSort() - only if you already have a presorted list and want to insert just - a few additional items. - - \sa insert(), compareItems(), current(), sort() -*/ - -/*! - \fn void Q3PtrList::append( const type *item ) - - Inserts the \a item at the end of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( count(), item )}. - - \a item must not be 0. - - \sa insert(), current(), prepend() -*/ - -/*! - \fn void Q3PtrList::prepend( const type *item ) - - Inserts the \a item at the start of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( 0, item )}. - - \a item must not be 0. - - \sa append(), insert(), current() -*/ - -/*! - \fn bool Q3PtrList::remove( uint index ) - - Removes the item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is \c{0..(count() - 1)} - inclusive. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove() - - \overload - - Removes the current list item. - - Returns TRUE if successful, i.e. if the current item isn't 0; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove( const type *item ) - - \overload - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call removeRef(). - - If \a item is NULL then the current item is removed from the list. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), - current() -*/ - -/*! - \fn bool Q3PtrList::removeRef( const type *item ) - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa remove(), clear(), setAutoDelete(), current() -*/ - -/*! - \fn void Q3PtrList::removeNode( Q3LNode *node ) - - Removes the \a node from the list. - - This node must exist in the list, otherwise the program may crash. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list will become the new current list item. - The current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the item succeeding this item or to the preceding item if - the removed item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa takeNode(), currentNode() remove() removeRef() -*/ - -/*! - \fn bool Q3PtrList::removeFirst() - - Removes the first item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeLast(), setAutoDelete(), current() remove() -*/ - -/*! - \fn bool Q3PtrList::removeLast() - - Removes the last item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The last item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeFirst(), setAutoDelete(), current() -*/ - -/*! - \fn type *Q3PtrList::take( uint index ) - - Takes the item at position \a index out of the list without - deleting it (even if \link setAutoDelete() auto-deletion\endlink - is enabled). - - Returns a pointer to the item taken out of the list, or 0 if the - index is out of range. The valid range is \c{0..(count() - 1)} - inclusive. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::take() - - \overload - - Takes the current item out of the list without deleting it (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - - Returns a pointer to the item taken out of the list, or 0 if - the current item is 0. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::takeNode( Q3LNode *node ) - - Takes the \a node out of the list without deleting its item (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - Returns a pointer to the item taken out of the list. - - This node must exist in the list, otherwise the program may crash. - - The first item in the list becomes the new current list item. - - All list iterators that refer to the taken item will be set to - point to the item succeeding this item or to the preceding item if - the taken item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), currentNode() -*/ - -/*! - \fn void Q3PtrList::clear() - - Removes all items from the list. - - The removed items are deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - All list iterators that access this list will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn int Q3PtrList::find( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findRef(). - - \sa findNext(), findRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findNext( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findNextRef(). - - \sa find(), findNextRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findRef( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than find() because find() - compares \a item with each list item using compareItems(), whereas - this function only compares the pointers. - - \sa findNextRef(), find(), current() -*/ - -/*! - \fn int Q3PtrList::findNextRef( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than findNext() because - findNext() compares \a item with each list item using - compareItems(), whereas this function only compares the pointers. - - \sa findRef(), findNext(), current() -*/ - -/*! - \fn uint Q3PtrList::contains( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - The compareItems() function is called when looking for the \a item - in the list. If compareItems() is not reimplemented, it is more - efficient to call containsRef(). - - This function does not affect the current list item. - - \sa containsRef(), compareItems() -*/ - -/*! - \fn uint Q3PtrList::containsRef( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - Calling this function is much faster than contains() because - contains() compares \a item with each list item using - compareItems(), whereas his function only compares the pointers. - - This function does not affect the current list item. - - \sa contains() -*/ - -/*! - \fn type *Q3PtrList::at( uint index ) - - Returns a pointer to the item at position \a index in the list, or - 0 if the index is out of range. - - Sets the current list item to this item if \a index is valid. The - valid range is \c{0..(count() - 1)} inclusive. - - This function is very efficient. It starts scanning from the first - item, last item, or current item, whichever is closest to \a - index. - - \sa current() -*/ - -/*! - \fn int Q3PtrList::at() const - - \overload - - Returns the index of the current list item. The returned value is - -1 if the current item is 0. - - \sa current() -*/ - -/*! - \fn type *Q3PtrList::current() const - - Returns a pointer to the current list item. The current item may - be 0 (implies that the current index is -1). - - \sa at() -*/ - -/*! - \fn Q3LNode *Q3PtrList::currentNode() const - - Returns a pointer to the current list node. - - The node can be kept and removed later using removeNode(). The - advantage is that the item can be removed directly without - searching the list. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), takeNode(), current() -*/ - -/*! - \fn type *Q3PtrList::getFirst() const - - Returns a pointer to the first item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa first(), getLast() -*/ - -/*! - \fn type *Q3PtrList::getLast() const - - Returns a pointer to the last item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa last(), getFirst() -*/ - -/*! - \fn type *Q3PtrList::first() - - Returns a pointer to the first item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getFirst(), last(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::last() - - Returns a pointer to the last item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getLast(), first(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::next() - - Returns a pointer to the item succeeding the current item. Returns - 0 if the current item is 0 or equal to the last item. - - Makes the succeeding item current. If the current item before this - function call was the last item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::prev() - - Returns a pointer to the item preceding the current item. Returns - 0 if the current item is 0 or equal to the first item. - - Makes the preceding item current. If the current item before this - function call was the first item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), next(), current() -*/ - -/*! - \fn void Q3PtrList::toVector( Q3GVector *vec ) const - - Stores all list items in the vector \a vec. - - The vector must be of the same item type, otherwise the result - will be undefined. -*/ - -/*! - \typedef Q3PtrList::iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::Iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::ConstIterator - - \internal -*/ - -/*! - \typedef Q3PtrList::const_iterator - - \internal -*/ - -/*! - \fn Q3PtrList::constBegin() const - - \internal -*/ - -/*! - \fn Q3PtrList::constEnd() const - - \internal -*/ - -/*! - \fn Q3PtrList::erase(Iterator) - - \internal -*/ - - -/***************************************************************************** - Q3PtrListIterator documentation - *****************************************************************************/ - -/*! - \class Q3PtrListIterator - \brief The Q3PtrListIterator class provides an iterator for - Q3PtrList collections. - \compat - - Define a template instance Q3PtrListIterator\ to create a list - iterator that operates on Q3PtrList\ (list of X*). - - The following example is similar to the - example in the Q3PtrList class documentation, - but it uses Q3PtrListIterator. The class Employee is - defined there. - - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 - - Using a list iterator is a more robust way of traversing the list - than using the Q3PtrList member functions \link Q3PtrList::first() - first\endlink(), \link Q3PtrList::next() next\endlink(), \link - Q3PtrList::current() current\endlink(), etc., as many iterators can - traverse the same list independently. - - An iterator has its own current list item and can get the next and - previous list items. It doesn't modify the list in any way. - - When an item is removed from the list, all iterators that point to - that item are updated to point to Q3PtrList::current() instead to - avoid dangling references. - - \sa Q3PtrList -*/ - -/*! - \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList &list ) - - Constructs an iterator for \a list. The current iterator item is - set to point on the first item in the \a list. -*/ - -/*! - \fn Q3PtrListIterator::~Q3PtrListIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrListIterator::count() const - - Returns the number of items in the list this iterator operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrListIterator::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrListIterator::atFirst() const - - Returns TRUE if the current iterator item is the first list item; - otherwise returns FALSE. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3PtrListIterator::atLast() const - - Returns TRUE if the current iterator item is the last list item; - otherwise returns FALSE. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toFirst() - - Sets the current iterator item to point to the first list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toLast() - - Sets the current iterator item to point to the last list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toFirst(), atLast() -*/ - -/*! - \fn Q3PtrListIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::operator*() - - Asterisk operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::current() const - - Returns a pointer to the current iterator item. If the iterator is - positioned before the first item in the list or after the last - item in the list, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the list is empty, it - sets the current item to 0 and returns 0 -*/ - -/*! - \fn type *Q3PtrListIterator::operator--() - - Prefix - makes the preceding item current and returns the new - current item. - - If the current iterator item was the first item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn Q3PtrListIterator& Q3PtrListIterator::operator=( const Q3PtrListIterator &it ) - - Assignment. Makes a copy of the iterator \a it and returns a - reference to this iterator. -*/ - -/*! - \class Q3StrList - \brief The Q3StrList class provides a doubly-linked list of char*. - \compat - - If you want a string list of \l{QString}s use QStringList. - - This class is a Q3PtrList\ instance (a list of char*). - - Q3StrList can make deep or shallow copies of the strings that are - inserted. - - A deep copy means that memory is allocated for the string and then - the string data is copied into that memory. A shallow copy is just - a copy of the pointer value and not of the string data itself. - - The disadvantage of shallow copies is that because a pointer can - be deleted only once, the program must put all strings in a - central place and know when it is safe to delete them (i.e. when - the strings are no longer referenced by other parts of the - program). This can make the program more complex. The advantage of - shallow copies is that they consume far less memory than deep - copies. It is also much faster to copy a pointer (typically 4 or 8 - bytes) than to copy string data. - - A Q3StrList that operates on deep copies will, by default, turn on - auto-deletion (see setAutoDelete()). Thus, by default Q3StrList - will deallocate any string copies it allocates. - - The virtual compareItems() function is reimplemented and does a - case-sensitive string comparison. The inSort() function will - insert strings in sorted order. In general it is fastest to insert - the strings as they come and sort() at the end; inSort() is useful - when you just have to add a few extra strings to an already sorted - list. - - The Q3StrListIterator class is an iterator for Q3StrList. -*/ - -/*! - \fn Q3StrList::operator QList() const - - Automatically converts a Q3StrList into a QList. -*/ - -/*! - \fn Q3StrList::Q3StrList( bool deepCopies ) - - Constructs an empty list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrList::Q3StrList(const Q3StrList &list) - \fn Q3StrList::Q3StrList(const QList &list) - - Constructs a copy of \a list. -*/ - -/*! - \fn Q3StrList::~Q3StrList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) - \fn Q3StrList &Q3StrList::operator=(const QList &list) - - Assigns \a list to this list and returns a reference to this list. -*/ - -/*! - \class Q3StrIList - \brief The Q3StrIList class provides a doubly-linked list of char* - with case-insensitive comparison. - \compat - - This class is a Q3PtrList\ instance (a list of char*). - - Q3StrIList is identical to Q3StrList except that the virtual - compareItems() function is reimplemented to compare strings - case-insensitively. The inSort() function inserts strings in a - sorted order. In general it is fastest to insert the strings as - they come and sort() at the end; inSort() is useful when you just - have to add a few extra strings to an already sorted list. - - The Q3StrListIterator class works for Q3StrIList. - - \sa QStringList -*/ - -/*! - \fn Q3StrIList::Q3StrIList( bool deepCopies ) - - Constructs a list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrIList::~Q3StrIList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, - Q3PtrCollection::Item item2 ) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a item1 == \a item2 - \i nonzero if \a item1 != \a item2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return three values and use it to sort by: - - \list - \i 0 if \a item1 == \a item2 - \i \> 0 (positive integer) if \a item1 \> \a item2 - \i \< 0 (negative integer) if \a item1 \< \a item2 - \endlist - - inSort() requires that compareItems() is implemented as described - here. - - This function should not modify the list because some const - functions call compareItems(). - - The default implementation compares the pointers. -*/ - -/*! - \fn QDataStream& Q3PtrList::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a list item from the stream \a s and returns a reference to - the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrList::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a list item, \a item to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! \fn iterator Q3PtrList::begin() -\internal -*/ -/*! \fn const_iterator Q3PtrList::begin() const -\internal -*/ -/*! \fn iterator Q3PtrList::end() -\internal -*/ -/*! \fn const_iterator Q3PtrList::end() const -\internal -*/ - -/*! - \class Q3StrListIterator - \brief The Q3StrListIterator class is an iterator for the Q3StrList - and Q3StrIList classes. - \compat - - This class is a Q3PtrListIterator\ instance. It can traverse - the strings in the Q3StrList and Q3StrIList classes. -*/ - - -/* - \class Q3PtrListAutoDelete - \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. - \compat - - A Q3PtrListAutoDelete is identical to a Q3PtrList with - setAutoDelete(TRUE). -*/ diff --git a/doc/src/q3ptrqueue.qdoc b/doc/src/q3ptrqueue.qdoc deleted file mode 100644 index b3af5f6..0000000 --- a/doc/src/q3ptrqueue.qdoc +++ /dev/null @@ -1,230 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrQueue - \brief The Q3PtrQueue class is a template class that provides a queue. - \compat - - Q3ValueVector can be used as an STL-compatible alternative to this - class. - - A template instance Q3PtrQueue\ is a queue that operates on - pointers to X (X*). - - A queue is a first in, first out structure. Items are added to the - tail of the queue with enqueue() and retrieved from the head with - dequeue(). You can peek at the head item without dequeing it using - head(). - - You can control the queue's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes, current() and - remove() are provided; both operate on the head(). - - \sa Q3PtrList Q3PtrStack -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue () - - Creates an empty queue with autoDelete() set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue& queue ) - - Creates a queue from \a queue. - - Only the pointers are copied; the items are not. The autoDelete() - flag is set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::~Q3PtrQueue() - - Destroys the queue. Items in the queue are deleted if autoDelete() - is TRUE. -*/ - -/*! - \fn Q3PtrQueue& Q3PtrQueue::operator= (const Q3PtrQueue& queue) - - Assigns \a queue to this queue and returns a reference to this - queue. - - This queue is first cleared and then each item in \a queue is - enqueued to this queue. Only the pointers are copied. - - \warning The autoDelete() flag is not modified. If it is TRUE for - both \a queue and this queue, deleting the two lists will cause \e - double-deletion of the items. -*/ - -/*! - \fn bool Q3PtrQueue::isEmpty() const - - Returns TRUE if the queue is empty; otherwise returns FALSE. - - \sa count() dequeue() head() -*/ - -/*! - \fn void Q3PtrQueue::enqueue (const type* d) - - Adds item \a d to the tail of the queue. - - \sa count() dequeue() -*/ - -/*! - \fn type* Q3PtrQueue::dequeue () - - Takes the head item from the queue and returns a pointer to it. - Returns 0 if the queue is empty. - - \sa enqueue() count() -*/ - -/*! - \fn bool Q3PtrQueue::remove() - - Removes the head item from the queue, and returns TRUE if there - was an item, i.e. the queue wasn't empty; otherwise returns FALSE. - - The item is deleted if autoDelete() is TRUE. - - \sa head() isEmpty() dequeue() -*/ - -/*! - \fn void Q3PtrQueue::clear() - - Removes all items from the queue, and deletes them if autoDelete() - is TRUE. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrQueue::count() const - - Returns the number of items in the queue. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::head() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn Q3PtrQueue::operator type*() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::current() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn bool Q3PtrQueue::autoDelete() const - - Returns the setting of the auto-delete option. The default is - FALSE. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrQueue::setAutoDelete( bool enable ) - - Sets the queue to auto-delete its contents if \a enable is TRUE - and not to delete them if \a enable is FALSE. - - If auto-deleting is turned on, all the items in a queue are - deleted when the queue itself is deleted. This can be quite - convenient if the queue has the only pointer to the items. - - The default setting is FALSE, for safety. If you turn it on, be - careful about copying the queue: you might find yourself with two - queues deleting the same items. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a queue item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a queue item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/q3ptrstack.qdoc b/doc/src/q3ptrstack.qdoc deleted file mode 100644 index 1650d69..0000000 --- a/doc/src/q3ptrstack.qdoc +++ /dev/null @@ -1,217 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrStack - \brief The Q3PtrStack class is a template class that provides a stack. - \compat - - Q3ValueStack is an STL-compatible alternative to this class. - - Define a template instance Q3PtrStack\ to create a stack that - operates on pointers to X, (X*). - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). Use top() to get a reference to the top element - without changing the stack. - - You can control the stack's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes current() and - remove() are provided; they both operate on the top(). - - \sa Q3PtrList Q3PtrQueue -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack () - - Creates an empty stack. -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack& s) - - Creates a stack by making a shallow copy of another stack \a s. -*/ - -/*! - \fn Q3PtrStack::~Q3PtrStack () - - Destroys the stack. All items will be deleted if autoDelete() is - true. -*/ - -/*! - \fn Q3PtrStack& Q3PtrStack::operator= (const Q3PtrStack& s) - - Sets the contents of this stack by making a shallow copy of - another stack \a s. Elements currently in this stack will be - deleted if autoDelete() is true. -*/ - -/*! - \fn bool Q3PtrStack::isEmpty () const - - Returns true if the stack contains no elements; otherwise returns - false. -*/ - -/*! - \fn void Q3PtrStack::push (const type* d) - - Adds an element \a d to the top of the stack. Last in, first out. -*/ - -/*! - \fn type* Q3PtrStack::pop () - - Removes the top item from the stack and returns it. The stack must - not be empty. -*/ - -/*! - \fn bool Q3PtrStack::remove () - - Removes the top item from the stack and deletes it if autoDelete() - is true. Returns true if there was an item to pop; otherwise - returns false. - - \sa clear() -*/ - -/*! - \fn void Q3PtrStack::clear() - - Removes all items from the stack, deleting them if autoDelete() is - true. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrStack::count() const - - Returns the number of items in the stack. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrStack::top () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn Q3PtrStack::operator type* ()const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn type* Q3PtrStack::current () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn bool Q3PtrStack::autoDelete() const - - The same as Q3PtrCollection::autoDelete(). Returns true if - the auto-delete option is set. If the option is set, the - stack auto-deletes its contents. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrStack::setAutoDelete(bool enable) - - Defines whether this stack auto-deletes its contents. The same as - Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete - is turned on. - - If auto-deleting is turned on, all the items in the stack are - deleted when the stack itself is deleted. This is convenient if - the stack has the only pointers to the items. - - The default setting is false, for safety. If you turn it on, be - careful about copying the stack, or you might find yourself with - two stacks deleting the same items. - - Note that the auto-delete setting may also affect other functions in - subclasses. For example, a subclass that has a remove() function - will remove the item from its data structure, and if auto-delete is - enabled, will also delete the item. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) - - Reads a stack item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrStack::write(QDataStream& s, - Q3PtrCollection::Item item) const - - Writes a stack item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/q3ptrvector.qdoc b/doc/src/q3ptrvector.qdoc deleted file mode 100644 index fa78de5..0000000 --- a/doc/src/q3ptrvector.qdoc +++ /dev/null @@ -1,427 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrVector - \brief The Q3PtrVector class is a template collection class that - provides a vector (array). - \compat - - Q3ValueVector is an STL-compatible alternative to this class. - - Q3PtrVector is implemented as a template class. Defines a template - instance Q3PtrVector\ to create a vector that contains pointers - to X (X*). - - A vector is the same as an array. The main difference between - Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the - elements, whereas Q3MemArray stores the elements themselves (i.e. - Q3MemArray is value-based and Q3PtrVector is pointer-based). - - Items are added to the vector using insert() or fill(). Items are - removed with remove(). You can get a pointer to an item at a - particular index position using at(). - - Unless otherwise stated, all functions that remove items from the - vector will also delete the element pointed to if \link - setAutoDelete() auto-deletion\endlink is enabled. By default, - auto-deletion is disabled; see setAutoDelete(). This behavior can - be changed in a subclass by reimplementing the virtual function - deleteItem(). - - Functions that compare items (find() and sort() for example) will - do so using the virtual function compareItems(). The default - implementation of this function only compares the pointer values. - Reimplement compareItems() in a subclass to get searching and - sorting based on the item contents. You can perform a linear - search for a pointer in the vector using findRef(), or a binary - search (of a sorted vector) using bsearch(). You can count the - number of times an item appears in the vector with contains() or - containsRef(). - - \sa Q3MemArray -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector() - - Constructs a null vector. - - \sa isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(uint size) - - Constructs an vector with room for \a size items. Makes a null - vector if \a size == 0. - - All \a size positions in the vector are initialized to 0. - - \sa size(), resize(), isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector &v) - - Constructs a copy of \a v. Only the pointers are copied (i.e. - shallow copy). -*/ - -/*! - \fn Q3PtrVector::~Q3PtrVector() - - Removes all items from the vector, and destroys the vector itself. - - \sa clear() -*/ - -/*! - \fn Q3PtrVector &Q3PtrVector::operator=(const Q3PtrVector &v) - - Assigns \a v to this vector and returns a reference to this - vector. - - This vector is first cleared and then all the items from \a v are - copied into the vector. Only the pointers are copied (i.e. shallow - copy). - - \sa clear() -*/ - -/*! - \fn type **Q3PtrVector::data() const - - Returns a pointer to the actual vector data, which is an array of - type*. - - The vector is a null vector if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3PtrVector::size() const - - Returns the size of the vector, i.e. the number of vector - positions. This is also the maximum number of items the vector can - hold. - - The vector is a null vector if size() == 0. - - \sa isNull(), resize(), count() -*/ - -/*! - \fn uint Q3PtrVector::count() const - - Returns the number of items in the vector. The vector is empty if - count() == 0. - - \sa isEmpty(), size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::isEmpty() const - - Returns true if the vector is empty; otherwise returns false. - - \sa count() -*/ - -/*! - \fn bool Q3PtrVector::isNull() const - - Returns true if the vector is null; otherwise returns false. - - A null vector has size() == 0 and data() == 0. - - \sa size() -*/ - -/*! - \fn bool Q3PtrVector::resize(uint size) - - Resizes (expands or shrinks) the vector to \a size elements. The - vector becomes a null vector if \a size == 0. - - Any items at position \a size or beyond in the vector are removed. - New positions are initialized to 0. - - Returns true if successful, i.e. if the memory was successfully - allocated; otherwise returns false. - - \sa size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::insert(uint i, const type *d) - - Sets position \a i in the vector to contain the item \a d. \a i - must be less than size(). Any previous element in position \a i is - removed. - - Returns true if \a i is within range; otherwise returns false. - - \sa at() -*/ - -/*! - \fn bool Q3PtrVector::remove(uint i) - - Removes the item at position \a i in the vector, if there is one. - \a i must be less than size(). - - Returns true if \a i is within range; otherwise returns false. - - \sa take(), at() -*/ - -/*! - \fn type* Q3PtrVector::take(uint i) - - Returns the item at position \a i in the vector, and removes that - item from the vector. \a i must be less than size(). If there is - no item at position \a i, 0 is returned. - - Unlike remove(), this function does \e not call deleteItem() for - the removed item. - - \sa remove(), at() -*/ - -/*! - \fn void Q3PtrVector::clear() - - Removes all items from the vector, and destroys the vector itself. - - The vector becomes a null vector. - - \sa isNull() -*/ - -/*! - \fn bool Q3PtrVector::fill(const type *d, int size) - - Inserts item \a d in all positions in the vector. Any existing - items are removed. If \a d is 0, the vector becomes empty. - - If \a size >= 0, the vector is first resized to \a size. By - default, \a size is -1. - - Returns true if successful, i.e. \a size is the same as the - current size, or \a size is larger and the memory has successfully - been allocated; otherwise returns false. - - \sa resize(), insert(), isEmpty() -*/ - -/*! - \fn void Q3PtrVector::sort() - - Sorts the items in ascending order. Any empty positions will be - put last. - - Compares items using the virtual function compareItems(). - - \sa bsearch() -*/ - -/*! - \fn int Q3PtrVector::bsearch(const type* d) const - - In a sorted array, finds the first occurrence of \a d using a - binary search. For a sorted array, this is generally much faster - than find(), which performs a linear search. - - Returns the position of \a d, or -1 if \a d could not be found. \a - d must not be 0. - - Compares items using the virtual function compareItems(). - - \sa sort(), find() -*/ - - -/*! - \fn int Q3PtrVector::findRef(const type *d, uint i) const - - Finds the first occurrence of the item pointer \a d in the vector - using a linear search. The search starts at position \a i, which - must be less than size(). \a i is by default 0; i.e. the search - starts at the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - This function does \e not use compareItems() to compare items. - - Use the much faster bsearch() to search a sorted vector. - - \sa find(), bsearch() -*/ - -/*! - \fn int Q3PtrVector::find(const type *d, uint i) const - - Finds the first occurrence of item \a d in the vector using a - linear search. The search starts at position \a i, which must be - less than size(). \a i is by default 0; i.e. the search starts at - the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - Compares items using the virtual function compareItems(). - - Use the much faster bsearch() to search a sorted vector. - - \sa findRef(), bsearch() -*/ - - -/*! - \fn uint Q3PtrVector::containsRef(const type *d) const - - Returns the number of occurrences of the item pointer \a d in the - vector. - - This function does \e not use compareItems() to compare items. - - \sa findRef() -*/ - -/*! - \fn uint Q3PtrVector::contains(const type *d) const - - Returns the number of occurrences of item \a d in the vector. - - Compares items using the virtual function compareItems(). - - \sa containsRef() -*/ - -/*! - \fn type *Q3PtrVector::operator[](int i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). - - Equivalent to at(\a i). - - \sa at() -*/ - -/*! - \fn type *Q3PtrVector::at(uint i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). -*/ - - -/*! - \fn void Q3PtrVector::toList(Q3GList *list) const - - \internal - - Copies all items in this vector to the list \a list. \a list is - first cleared and then all items are appended to \a list. - - \sa Q3PtrList, Q3PtrStack, Q3PtrQueue -*/ - -/*! - \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, - Q3PtrCollection::Item d2) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a d1 == \a d2 - \i nonzero if \a d1 != \a d2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return one of three values and use it to - sort by: - \list - \i 0 if \a d1 == \a d2 - \i \> 0 (positive integer) if \a d1 \> \a d2 - \i \< 0 (negative integer) if \a d1 \< \a d2 - \endlist - - The sort() and bsearch() functions require compareItems() to be - implemented as described here. - - This function should not modify the vector because some const - functions call compareItems(). -*/ - -/*! - \fn QDataStream& Q3PtrVector::read(QDataStream &s, - Q3PtrCollection::Item &item) - - Reads a vector item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrVector::write(QDataStream &s, - Q3PtrCollection::Item item) const - - Writes a vector item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! - \fn bool Q3PtrVector::operator==(const Q3PtrVector &v) const - - Returns true if this vector and \a v are equal; otherwise returns - false. -*/ diff --git a/doc/src/q3sqlfieldinfo.qdoc b/doc/src/q3sqlfieldinfo.qdoc deleted file mode 100644 index ba064f3..0000000 --- a/doc/src/q3sqlfieldinfo.qdoc +++ /dev/null @@ -1,234 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3SqlFieldInfo - \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. - - \compat - - Q3SqlFieldInfo objects only store meta data; field values are - stored in QSqlField objects. - - All values must be set in the constructor, and may be retrieved - using isRequired(), type(), length(), precision(), defaultValue(), - name(), isGenerated() and typeID(). - - \sa Q3SqlRecordInfo -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, - QVariant::Type typ, - int required, - int len, - int prec, - const QVariant& defValue, - int typeID, - bool generated, - bool trim, - bool calculated) - - Constructs a Q3SqlFieldInfo with the following parameters: - \table - \row \i \a name \i the name of the field. - \row \i \a typ \i the field's type in a QVariant. - \row \i \a required \i greater than 0 if the field is required, 0 - if its value can be NULL and less than 0 if it cannot be - determined whether the field is required or not. - \row \i \a len \i the length of the field. Note that for - non-character types some databases return either the length in - bytes or the number of digits. -1 signifies that the length cannot - be determined. - \row \i \a prec \i the precision of the field, or -1 if the field - has no precision or it cannot be determined. - \row \i \a defValue \i the default value that is inserted into - the table if none is specified by the user. QVariant() if there is - no default value or it cannot be determined. - \row \i \a typeID \i the internal typeID of the database system - (only useful for low-level programming). 0 if unknown. - \row \i \a generated \i TRUE indicates that this field should be - included in auto-generated SQL statments, e.g. in Q3SqlCursor. - \row \i \a trim \i TRUE indicates that widgets should remove - trailing whitespace from character fields. This does not affect - the field value but only its representation inside widgets. - \row \i \a calculated \i TRUE indicates that the value of this - field is calculated. The value of calculated fields can by - modified by subclassing Q3SqlCursor and overriding - Q3SqlCursor::calculateField(). - \endtable -*/ - -/*! - \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() - - Destroys the object and frees any allocated resources. -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) - - Creates a Q3SqlFieldInfo object with the type and the name of the - QSqlField \a other. -*/ - -/*! - \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const - - Assigns \a other to this field info and returns a reference to it. -*/ - -/*! - \fn QSqlField Q3SqlFieldInfo::toField() const - - Returns an empty QSqlField based on the information in this - Q3SqlFieldInfo. -*/ - -/*! - \fn int Q3SqlFieldInfo::isRequired() const - - Returns a value greater than 0 if the field is required (NULL - values are not allowed), 0 if it isn't required (NULL values are - allowed) or less than 0 if it cannot be determined whether the - field is required or not. -*/ - -/*! - \fn QVariant::Type Q3SqlFieldInfo::type() const - - Returns the field's type or QVariant::Invalid if the type is - unknown. -*/ - -/*! - \fn int Q3SqlFieldInfo::length() const - - Returns the field's length. For fields storing text the return - value is the maximum number of characters the field can hold. For - non-character fields some database systems return the number of - bytes needed or the number of digits allowed. If the length cannot - be determined -1 is returned. -*/ - -/*! - \fn int Q3SqlFieldInfo::precision() const - - Returns the field's precision or -1 if the field has no precision - or it cannot be determined. -*/ - -/*! - \fn QVariant Q3SqlFieldInfo::defaultValue() const - - Returns the field's default value or an empty QVariant if the - field has no default value or the value couldn't be determined. - The default value is the value inserted in the database when it - is not explicitly specified by the user. -*/ - -/*! - \fn QString Q3SqlFieldInfo::name() const - - Returns the name of the field in the SQL table. -*/ - -/*! - \fn int Q3SqlFieldInfo::typeID() const - - Returns the internal type identifier as returned from the database - system. The return value is 0 if the type is unknown. -*/ - -/*! - \fn bool Q3SqlFieldInfo::isGenerated() const - - Returns TRUE if the field should be included in auto-generated - SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. - - \sa setGenerated() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isTrim() const - - Returns TRUE if trailing whitespace should be removed from - character fields; otherwise returns FALSE. - - \sa setTrim() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isCalculated() const - - Returns TRUE if the field is calculated; otherwise returns FALSE. - - \sa setCalculated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setTrim(bool trim) - - If \a trim is TRUE widgets should remove trailing whitespace from - character fields. This does not affect the field value but only - its representation inside widgets. - - \sa isTrim() -*/ - -/*! - \fn void Q3SqlFieldInfo::setGenerated(bool generated) - - \a generated set to FALSE indicates that this field should not appear - in auto-generated SQL statements (for example in Q3SqlCursor). - - \sa isGenerated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setCalculated(bool calculated) - - \a calculated set to TRUE indicates that this field is a calculated - field. The value of calculated fields can by modified by subclassing - Q3SqlCursor and overriding Q3SqlCursor::calculateField(). - - \sa isCalculated() -*/ diff --git a/doc/src/q3sqlrecordinfo.qdoc b/doc/src/q3sqlrecordinfo.qdoc deleted file mode 100644 index 64236d2..0000000 --- a/doc/src/q3sqlrecordinfo.qdoc +++ /dev/null @@ -1,89 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3SqlRecordInfo - \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. - - \compat - - This class is a list that holds a set of database field meta - data. Use contains() to see if a given field name exists in the - record, and use find() to get a QSqlFieldInfo record for a named - field. - - \sa Q3SqlFieldInfo -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo() - - Constructs an empty record info object. -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) - - Constructs a copy of \a other. -*/ - -/*! - \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const - - Returns the number of times a field called \a fieldName occurs in - the record. Returns 0 if no field by that name could be found. -*/ - -/*! - \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const - - Returns a QSqlFieldInfo object for the first field in the record - which has the field name \a fieldName. If no matching field is - found then an empty QSqlFieldInfo object is returned. -*/ - -/*! - \fn QSqlRecord Q3SqlRecordInfo::toRecord() const - - Returns an empty QSqlRecord based on the field information - in this Q3SqlRecordInfo. -*/ diff --git a/doc/src/q3valuelist.qdoc b/doc/src/q3valuelist.qdoc deleted file mode 100644 index fd73763..0000000 --- a/doc/src/q3valuelist.qdoc +++ /dev/null @@ -1,569 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueList - \brief The Q3ValueList class is a value-based template class that - provides lists. - \compat - - Q3ValueList is a Qt implementation of an STL-like list container. - It can be used in your application if the standard \c list is not - available for your target platforms. - - Q3ValueList\ defines a template instance to create a list of - values that all have the class T. Note that Q3ValueList does not - store pointers to the members of the list; it holds a copy of - every member. This is why these kinds of classes are called "value - based"; Q3PtrList and Q3Dict are "pointer based". - - Q3ValueList contains and manages a collection of objects of type T - and provides iterators that allow the contained objects to be - addressed. Q3ValueList owns the contained items. For more relaxed - ownership semantics, see Q3PtrCollection and friends which are - pointer-based containers. - - Some classes cannot be used within a Q3ValueList, for example, all - classes derived from QObject and thus all classes that implement - widgets. Only values can be used in a Q3ValueList. To qualify as a - value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - In addition, some compilers (e.g. Sun CC) might require that the - class provides an equality operator (operator==()). - - Q3ValueList's function naming is consistent with the other Qt - classes (e.g. count(), isEmpty()). Q3ValueList also provides extra - functions for compatibility with STL algorithms, such as size() - and empty(). Programmers already familiar with the STL \c list may - prefer to use the STL-compatible functions. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 - - - Notice that the latest changes to Mary's salary did not affect the - value in the list because the list created a copy of Mary's entry. - - There are several ways to find items in the list. The begin() and - end() functions return iterators to the beginning and end of the - list. The advantage of getting an iterator is that you can move - forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the item which is one \e past the last item in the - container. The past-the-end iterator is still associated with the - list it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the list is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - It is safe to have multiple iterators a the list at the same - time. If some member of the list is removed, only iterators - pointing to the removed member become invalid. Inserting into the - list does not invalidate any iterator. For convenience, the - function last() returns a reference to the last item in the list, - and first() returns a reference to the first item. If the - list is empty(), both last() and first() have undefined behavior - (your application will crash or do unpredictable things). Use - last() and first() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 - - Because Q3ValueList is value-based there is no need to be careful - about deleting items in the list. The list holds its own copies - and will free them if the corresponding member or the list itself - is deleted. You can force the list to free all of its items with - clear(). - - Q3ValueList is shared implicitly, which means it can be copied in - constant time, i.e. O(1). If multiple Q3ValueList instances share - the same data and one needs to modify its contents, this modifying - instance makes a copy and modifies its private copy; therefore it - does not affect the other instances; this takes O(n) time. This is - often called "copy on write". If a Q3ValueList is being used in a - multi-threaded program, you must protect all access to the list. - See \l QMutex. - - There are several ways to insert items into the list. The - prepend() and append() functions insert items at the beginning and - the end of the list respectively. The insert() function comes in - several flavors and can be used to add one or more items at - specific positions within the list. - - Items can also be removed from the list in several ways. There - are several variants of the remove() function, which removes a - specific item from the list. The remove() function will find and - remove items according to a specific item value. - - \sa Q3ValueListIterator -*/ - -/*! \typedef Q3ValueList::iterator - The list's iterator type, Q3ValueListIterator. */ -/*! \typedef Q3ValueList::const_iterator - The list's const iterator type, Q3ValueListConstIterator. */ -/*! \typedef Q3ValueList::value_type - The type of the object stored in the list, T. */ -/*! \typedef Q3ValueList::pointer - The pointer to T type. */ -/*! \typedef Q3ValueList::const_pointer - The const pointer to T type. */ -/*! \typedef Q3ValueList::reference - The reference to T type. */ -/*! \typedef Q3ValueList::const_reference - The const reference to T type. */ -/*! \typedef Q3ValueList::size_type - An unsigned integral type, used to represent various sizes. */ -/*! \typedef Q3ValueList::difference_type - \internal -*/ -/*! - \fn Q3ValueList::Q3ValueList() - - Constructs an empty list. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const Q3ValueList& l ) - \fn Q3ValueList::Q3ValueList( const QList& l ) - \fn Q3ValueList::Q3ValueList( const QLinkedList& l ) - - Constructs a copy of \a l. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const std::list& l ) - - Contructs a copy of \a l. - - This constructor is provided for compatibility with STL - containers. -*/ - -/*! - \fn Q3ValueList::~Q3ValueList() - - Destroys the list. References to the values in the list and all - iterators of this list become invalidated. Note that it is - impossible for an iterator to check whether or not it is valid: - Q3ValueList is highly tuned for performance, not for error - checking. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const Q3ValueList& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const std::list& l ) const - - \overload - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. - - This operator is provided for compatibility with STL containers. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const Q3ValueList& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. The cost of such an assignment is O(1) since Q3ValueList - is implicitly shared. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const QList& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const std::list& l ) - - \overload - - Assigns the contents of \a l to the list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn bool Q3ValueList::operator!= ( const Q3ValueList& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are unequal; otherwise returns - FALSE. -*/ - -/*! - \fn iterator Q3ValueList::insert( typename Q3ValueList::Iterator it, const T& x ) - - Inserts the value \a x in front of the item pointed to by the - iterator, \a it. - - Returns an iterator pointing at the inserted item. - - \sa append(), prepend() -*/ - -/*! - \fn uint Q3ValueList::remove( const T& x ) - - \overload - - Removes all items that have value \a x and returns the number of - removed items. -*/ - -/*! - \fn QDataStream& operator>>( QDataStream& s, Q3ValueList& l ) - - \relates Q3ValueList - - Reads a list, \a l, from the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList& l ) - - \overload - \relates Q3ValueList - - Writes a list, \a l, to the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn void Q3ValueList::insert( typename Q3ValueList::Iterator pos, - typename Q3ValueList::size_type n, const T& x ) - - \overload - - Inserts \a n copies of \a x before position \a pos. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator<< ( const T& x ) - - Adds the value \a x to the end of the list. - - Returns a reference to the list. -*/ - -/*! - \fn const T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) const - - Returns a const reference to the item with index \a i in the list. - It is up to you to check whether this item really exists. You can - do that easily with the count() function. However this operator - does not check whether \a i is in range and will deliver undefined - results if it does not exist. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) - - \overload - - Returns a non-const reference to the item with index \a i. -*/ - -/*! - \fn const_iterator Q3ValueList::at( typename Q3ValueList::size_type i ) const - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn iterator Q3ValueList::at( typename Q3ValueList::size_type i ) - - \overload - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - -*/ - -/*! - \fn iterator Q3ValueList::fromLast() - - \overload - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 - -*/ - -/*! - \fn const_iterator Q3ValueList::fromLast() const - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 - -*/ - -/*! - \fn Q3ValueList Q3ValueList::operator+( const Q3ValueList& l ) const - - Creates a new list and fills it with the items of this list. Then - the items of \a l are appended. Returns the new list. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator+= ( const Q3ValueList& l ) - - Appends the items of \a l to this list. Returns a reference to - this list. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator+= ( const T& x ) - - \overload - - Appends the value \a x to the list. Returns a reference to the - list. -*/ - -/*! - \fn iterator Q3ValueList::append( const T& x ) - - Inserts \a x at the end of the list. - - \sa insert(), prepend() -*/ - -/*! - \fn iterator Q3ValueList::prepend( const T& x ) - - Inserts \a x at the beginning of the list. - - \sa insert(), append() -*/ - -/*! - \fn iterator Q3ValueList::remove( typename Q3ValueList::Iterator it ) - - Removes the item pointed to by \a it from the list. No iterators - other than \a it or other iterators pointing at the same item as - \a it are invalidated. Returns an iterator to the next item after - \a it, or end() if there is no such item. - - \sa clear() -*/ - -/*! - \fn uint Q3ValueList::contains( const T& x ) const - - Returns the number of occurrences of the value \a x in the list. -*/ - -/*! - \class Q3ValueListIterator - \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. - \compat - - An iterator is a class for accessing the items of a container - class: a generalization of the index in an array. A pointer - into a "const char *" and an index into an "int[]" are both - iterators, and the general idea is to provide that functionality - for any data structure. - - The Q3ValueListIterator class is an iterator for Q3ValueList - instantiations. You can create the appropriate iterator type by - using the \c iterator typedef provided by Q3ValueList. - - The only way to access the items in a Q3ValueList is to use an - iterator. - - Example (see Q3ValueList for the complete code): - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 - - Q3ValueList is highly optimized for performance and memory usage. - This means that you must be careful: Q3ValueList does not know - about all its iterators and the iterators don't know to which list - they belong. This makes things very fast, but if you're not - careful, you can get spectacular bugs. Always make sure iterators - are valid before dereferencing them or using them as parameters to - generic algorithms in the STL. - - Using an invalid iterator is undefined (your application will - probably crash). Many Qt functions return const value lists; to - iterate over these you should make a copy and iterate over the - copy. - - For every Iterator there is a ConstIterator. When accessing a - Q3ValueList in a const environment or if the reference or pointer - to the list is itself const, then you must use the ConstIterator. - Its semantics are the same as the Iterator, but it only returns - const references. - - \sa Q3ValueList, Q3ValueListConstIterator -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) - \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList::iterator &o) - - Constucts a copy of iterator \a o. -*/ - -/*! - \class Q3ValueListConstIterator - \brief The Q3ValueListConstIterator class provides a const iterator - for Q3ValueList. - \compat - - In contrast to Q3ValueListIterator, this class is used to iterate - over a const list. It does not allow modification of the values of - the list since that would break const semantics. - - You can create the appropriate const iterator type by using the \c - const_iterator typedef provided by Q3ValueList. - - For more information on Q3ValueList iterators, see - Q3ValueListIterator. - - \sa Q3ValueListIterator, Q3ValueList -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::const_iterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::iterator &o) - - Constructs a copy of iterator \a o. -*/ - -/*! - \typedef Q3ValueList::Iterator - - This iterator is an instantiation of Q3ValueListIterator for the - same type as this Q3ValueList. In other words, if you instantiate - Q3ValueList, Iterator is a Q3ValueListIterator. Several - member function use it, such as Q3ValueList::begin(), which returns - an iterator pointing to the first item in the list. - - Functionally, this is almost the same as ConstIterator. The only - difference is that you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator ConstIterator -*/ - -/*! - \typedef Q3ValueList::ConstIterator - - This iterator is an instantiation of Q3ValueListConstIterator for - the same type as this Q3ValueList. In other words, if you - instantiate Q3ValueList, ConstIterator is a - Q3ValueListConstIterator. Several member function use it, such - as Q3ValueList::begin(), which returns an iterator pointing to the - first item in the list. - - Functionally, this is almost the same as Iterator. The only - difference is you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator Iterator -*/ - -/*! - \fn Q3ValueList::operator QList() const - - Automatically converts a Q3ValueList into a QList. -*/ diff --git a/doc/src/q3valuestack.qdoc b/doc/src/q3valuestack.qdoc deleted file mode 100644 index e3ae677..0000000 --- a/doc/src/q3valuestack.qdoc +++ /dev/null @@ -1,149 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueStack - \brief The Q3ValueStack class is a value-based template class that provides a stack. - \compat - - Define a template instance Q3ValueStack\ to create a stack of - values that all have the class X. - - Note that Q3ValueStack does not store pointers to the members of - the stack; it holds a copy of every member. That is why these - kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, - Q3Dict, etc., are "pointer based". - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). The top() function provides access to the topmost item - without removing it. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 - - Q3ValueStack is a specialized Q3ValueList provided for convenience. - All of Q3ValueList's functionality also applies to Q3PtrStack, for - example the facility to iterate over all elements using - Q3ValueStack::Iterator. See Q3ValueListIterator for further - details. - - Some classes cannot be used within a Q3ValueStack, for example - everything derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueStack. To - qualify as a value, the class must provide - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. -*/ - - -/*! - \fn Q3ValueStack::Q3ValueStack() - - Constructs an empty stack. -*/ - -/*! - \fn Q3ValueStack::~Q3ValueStack() - - Destroys the stack. References to the values in the stack and all - iterators of this stack become invalidated. Because Q3ValueStack is - highly tuned for performance, you won't see warnings if you use - invalid iterators because it is impossible for an iterator to - check whether or not it is valid. -*/ - - -/*! - \fn void Q3ValueStack::push( const T& d ) - - Adds element, \a d, to the top of the stack. Last in, first out. - - This function is equivalent to append(). - - \sa pop(), top() -*/ - -/*! - \fn T& Q3ValueStack::top() - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. Note that you must not - change the value the end() iterator points to. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - - -/*! - \fn const T& Q3ValueStack::top() const - - \overload - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - -/*! - \fn T Q3ValueStack::pop() - - Removes the top item from the stack and returns it. - - \sa top() push() -*/ - - - - - diff --git a/doc/src/q3valuevector.qdoc b/doc/src/q3valuevector.qdoc deleted file mode 100644 index 353b7fa..0000000 --- a/doc/src/q3valuevector.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueVector - \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. - \compat - - Q3ValueVector is a Qt implementation of an STL-like vector - container. It can be used in your application if the standard \c - vector is not available for your target platforms. - - Q3ValueVector\ defines a template instance to create a vector - of values that all have the class T. Q3ValueVector does not store - pointers to the members of the vector; it holds a copy of every - member. Q3ValueVector is said to be value based; in contrast, - Q3PtrList and Q3Dict are pointer based. - - Q3ValueVector contains and manages a collection of objects of type - T and provides random access iterators that allow the contained - objects to be addressed. Q3ValueVector owns the contained - elements. For more relaxed ownership semantics, see Q3PtrCollection - and friends, which are pointer-based containers. - - Q3ValueVector provides good performance if you append or remove - elements from the end of the vector. If you insert or remove - elements from anywhere but the end, performance is very bad. The - reason for this is that elements must to be copied into new - positions. - - Some classes cannot be used within a Q3ValueVector: for example, - all classes derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueVector. To - qualify as a value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e., a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - Q3ValueVector uses an STL-like syntax to manipulate and address the - objects it contains. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 - - As you can see, the most recent change to Joe's salary did not - affect the value in the vector because the vector created a copy - of Joe's entry. - - Many Qt functions return const value vectors; to iterate over - these you should make a copy and iterate over the copy. - - There are several ways to find items in the vector. The begin() - and end() functions return iterators to the beginning and end of - the vector. The advantage of getting an iterator is that you can - move forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the element which is one past the last element in - the container. The past-the-end iterator is still associated with - the vector it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the vector is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - The fastest way to access an element of a vector is by using - operator[]. This function provides random access and will return - a reference to the element located at the specified index. Thus, - you can access every element directly, in constant time, providing - you know the location of the element. It is undefined to access - an element that does not exist (your application will probably - crash). For example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 - - Whenever inserting, removing or referencing elements in a vector, - always make sure you are referring to valid positions. For - example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 - - The iterators provided by vector are random access iterators, - therefore you can use them with many generic algorithms, for - example, algorithms provided by the STL. - - It is safe to have multiple iterators on the vector at the same - time. Since Q3ValueVector manages memory dynamically, all iterators - can become invalid if a memory reallocation occurs. For example, - if some member of the vector is removed, iterators that point to - the removed element and to all following elements become - invalidated. Inserting into the middle of the vector will - invalidate all iterators. For convenience, the function back() - returns a reference to the last element in the vector, and front() - returns a reference to the first element. If the vector is - empty(), both back() and front() have undefined behavior (your - application will crash or do unpredictable things). Use back() and - front() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 - - Because Q3ValueVector manages memory dynamically, it is recommended - that you contruct a vector with an initial size. Inserting and - removing elements happens fastest when: - \list - \i Inserting or removing elements happens at the end() of the - vector; - \i The vector does not need to allocate additional memory. - \endlist - - By creating a Q3ValueVector with a sufficiently large initial size, - there will be less memory allocations. Do not use an initial size - that is too big, since it will still take time to construct all - the empty entries, and the extra space will be wasted if it is - never used. - - Because Q3ValueVector is value-based there is no need to be careful - about deleting elements in the vector. The vector holds its own - copies and will free them if the corresponding member or the - vector itself is deleted. You can force the vector to free all of - its items with clear(). - - Q3ValueVector is shared implicitly, which means it can be copied in - constant time. If multiple Q3ValueVector instances share the same - data and one needs to modify its contents, this modifying instance - makes a copy and modifies its private copy; it thus does not - affect the other instances. This is often called "copy on write". - If a Q3ValueVector is being used in a multi-threaded program, you - must protect all access to the vector. See QMutex. - - There are several ways to insert elements into the vector. The - push_back() function insert elements into the end of the vector, - and is usually fastest. The insert() function can be used to add - elements at specific positions within the vector. - - Items can be also be removed from the vector in several ways. - There are several variants of the erase() function which removes a - specific element, or range of elements, from the vector. - - Q3ValueVector stores its elements in contiguous memory. This means - that you can use a Q3ValueVector in any situation that requires an - array. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector() - - Constructs an empty vector without any elements. To create a - vector which reserves an initial amount of space for elements, use - \c Q3ValueVector(size_type n). -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector& v ) - - Constructs a copy of \a v. - - This operation costs O(1) time because Q3ValueVector is implicitly - shared. - - The first modification to the vector does takes O(n) time, because - the elements must be copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const std::vector& v ) - - This operation costs O(n) time because \a v is copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( QVector::size_type n, const T& val ) - - Constructs a vector with an initial size of \a n elements. Each - element is initialized with the value of \a val. -*/ - -/*! - \fn Q3ValueVector& Q3ValueVector::operator=( const Q3ValueVector& v ) - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of such an assignment is O(1) since - Q3ValueVector is implicitly shared. -*/ - -/*! - \fn Q3ValueVector& Q3ValueVector::operator=( const std::vector& v ) - - \overload - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of this assignment is O(n) since \a v is - copied. -*/ - -/*! - \fn T &Q3ValueVector::at( int i , bool* ok ) - - Returns a reference to the element with index \a i. If \a ok is - non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn const T &Q3ValueVector::at( int i , bool* ok ) const - - \overload - - Returns a const reference to the element with index \a i. If \a ok - is non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn void Q3ValueVector::resize( int n, const T& val = T() ) - - Changes the size of the vector to \a n. If \a n is greater than - the current size(), elements are added to the end and initialized - with the value of \a val. If \a n is less than size(), elements - are removed from the end. If \a n is equal to size() nothing - happens. -*/ diff --git a/doc/src/qalgorithms.qdoc b/doc/src/qalgorithms.qdoc deleted file mode 100644 index 7634322..0000000 --- a/doc/src/qalgorithms.qdoc +++ /dev/null @@ -1,651 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Generic Algorithms - \ingroup architecture - - \brief The header provides generic template-based algorithms. - - Qt provides a number of global template functions in \c - that work on containers and perform well-know - algorithms. You can use these algorithms with any \l {container - class} that provides STL-style iterators, including Qt's QList, - QLinkedList, QVector, QMap, and QHash classes. - - These functions have taken their inspiration from similar - functions available in the STL \c header. Most of them - have a direct STL equivalent; for example, qCopyBackward() is the - same as STL's copy_backward() algorithm. - - If STL is available on all your target platforms, you can use the - STL algorithms instead of their Qt counterparts. One reason why - you might want to use the STL algorithms is that STL provides - dozens and dozens of algorithms, whereas Qt only provides the most - important ones, making no attempt to duplicate functionality that - is already provided by the C++ standard. - - Most algorithms take \l {STL-style iterators} as parameters. The - algorithms are generic in the sense that they aren't bound to a - specific iterator class; you can use them with any iterators that - meet a certain set of requirements. - - Let's take the qFill() algorithm as an example. Unlike QVector, - QList has no fill() function that can be used to fill a list with - a particular value. If you need that functionality, you can use - qFill(): - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 - - qFill() takes a begin iterator, an end iterator, and a value. - In the example above, we pass \c list.begin() and \c list.end() - as the begin and end iterators, but this doesn't have to be - the case: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 - - Different algorithms can have different requirements for the - iterators they accept. For example, qFill() accepts two - \l {forward iterators}. The iterator types required are specified - for each algorithm. If an iterator of the wrong type is passed (for - example, if QList::ConstIterator is passed as an \l {output - iterator}), you will always get a compiler error, although not - necessarily a very informative one. - - Some algorithms have special requirements on the value type - stored in the containers. For example, qEqual() requires that the - value type supports operator==(), which it uses to compare items. - Similarly, qDeleteAll() requires that the value type is a - non-const pointer type (for example, QWidget *). The value type - requirements are specified for each algorithm, and the compiler - will produce an error if a requirement isn't met. - - \target binaryFind example - - The generic algorithms can be used on other container classes - than those provided by Qt and STL. The syntax of STL-style - iterators is modeled after C++ pointers, so it's possible to use - plain arrays as containers and plain pointers as iterators. A - common idiom is to use qBinaryFind() together with two static - arrays: one that contains a list of keys, and another that - contains a list of associated values. For example, the following - code will look up an HTML entity (e.g., \c &) in the \c - name_table array and return the corresponding Unicode value from - the \c value_table if the entity is recognized: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 - - This kind of code is for advanced users only; for most - applications, a QMap- or QHash-based approach would work just as - well: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 - - \section1 Types of Iterators - - The algorithms have certain requirements on the iterator types - they accept, and these are specified individually for each - function. The compiler will produce an error if a requirement - isn't met. - - \section2 Input Iterators - - An \e{input iterator} is an iterator that can be used for reading - data sequentially from a container. It must provide the following - operators: \c{==} and \c{!=} for comparing two iterators, unary - \c{*} for retrieving the value stored in the item, and prefix - \c{++} for advancing to the next item. - - The Qt containers' iterator types (const and non-const) are all - input iterators. - - \section2 Output Iterators - - An \e{output iterator} is an iterator that can be used for - writing data sequentially to a container or to some output - stream. It must provide the following operators: unary \c{*} for - writing a value (i.e., \c{*it = val}) and prefix \c{++} for - advancing to the next item. - - The Qt containers' non-const iterator types are all output - iterators. - - \section2 Forward Iterators - - A \e{forward iterator} is an iterator that meets the requirements - of both input iterators and output iterators. - - The Qt containers' non-const iterator types are all forward - iterators. - - \section2 Bidirectional Iterators - - A \e{bidirectional iterator} is an iterator that meets the - requirements of forward iterators but that in addition supports - prefix \c{--} for iterating backward. - - The Qt containers' non-const iterator types are all bidirectional - iterators. - - \section2 Random Access Iterators - - The last category, \e{random access iterators}, is the most - powerful type of iterator. It supports all the requirements of a - bidirectional iterator, and supports the following operations: - - \table - \row \i \c{i += n} \i advances iterator \c i by \c n positions - \row \i \c{i -= n} \i moves iterator \c i back by \c n positions - \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c - n positions ahead of iterator \c i - \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i - \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j - \row \i \c{i[n]} \i same as \c{*(i + n)} - \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i - \endtable - - QList and QVector's non-const iterator types are random access iterators. - - \sa {container classes}, -*/ - -/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) - \relates - - Copies the items from range [\a begin1, \a end1) to range [\a - begin2, ...), in the order in which they appear. - - The item at position \a begin1 is assigned to that at position \a - begin2; the item at position \a begin1 + 1 is assigned to that at - position \a begin2 + 1; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 - - \sa qCopyBackward(), {input iterators}, {output iterators} -*/ - -/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) - \relates - - Copies the items from range [\a begin1, \a end1) to range [..., - \a end2). - - The item at position \a end1 - 1 is assigned to that at position - \a end2 - 1; the item at position \a end1 - 2 is assigned to that - at position \a end2 - 2; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 - - \sa qCopy(), {bidirectional iterators} -*/ - -/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) - \relates - - Compares the items in the range [\a begin1, \a end1) with the - items in the range [\a begin2, ...). Returns true if all the - items compare equal; otherwise returns false. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) - \relates - - Fills the range [\a begin, \a end) with \a value. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 - - \sa qCopy(), {forward iterators} -*/ - -/*! \fn void qFill(Container &container, const T &value) - \relates - - \overload - - This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); -*/ - -/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) - \relates - - Returns an iterator to the first occurrence of \a value in a - container in the range [\a begin, \a end). Returns \a end if \a - value isn't found. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - If the items in the range are in ascending order, you can get - faster results by using qLowerBound() or qBinaryFind() instead of - qFind(). - - \sa qBinaryFind(), {input iterators} -*/ - -/*! \fn void qFind(const Container &container, const T &value) - \relates - - \overload - - This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); -*/ - -/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) - \relates - - Returns the number of occurrences of \a value in the range [\a begin, \a end), - which is returned in \a n. \a n is never initialized, the count is added to \a n. - It is the caller's responsibility to initialize \a n. - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 - - This function requires the item type (in the example above, - \c int) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qCount(const Container &container, const T &value, Size &n) -\relates - -\overload - -Instead of operating on iterators, as in the other overload, this function -operates on the specified \a container to obtain the number of instances -of \a value in the variable passed as a reference in argument \a n. -*/ - -/*! \fn void qSwap(T &var1, T &var2) - \relates - - Exchanges the values of variables \a var1 and \a var2. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates - - Sorts the items in range [\a begin, \a end) in ascending order - using the quicksort algorithm. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - \sa qStableSort(), {random access iterators} -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 - - To sort values in reverse order, pass - \l{qGreater()}{qGreater()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - An alternative to using qSort() is to put the items to sort in a - QMap, using the sort key as the QMap key. This is often more - convenient than defining a \a lessThan function. For example, the - following code shows how to sort a list of strings case - insensitively using QMap: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 - - \sa QMap -*/ - -/*! \fn void qSort(Container &container) - \relates - - \overload - - This is the same as qSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates - - Sorts the items in range [\a begin, \a end) in ascending order - using a stable sorting algorithm. - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - \sa qSort(), {random access iterators} -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 - - Note that earlier versions of Qt allowed using a lessThan function that took its - arguments by non-const reference. From 4.3 and on this is no longer possible, - the arguments has to be passed by const reference or value. - - To sort values in reverse order, pass - \l{qGreater()}{qGreater()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. -*/ - -/*! - \fn void qStableSort(Container &container) - \relates - - \overload - - This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the first ocurrence of \a value. If no - such item is found, returns the position where it should be - inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qLowerBound() can be used in conjunction with qUpperBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 - - \sa qUpperBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qLowerBound(const Container &container, const T &value) - \relates - - \overload - - For read-only iteration over containers, this function is broadly equivalent to - qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it - returns a const iterator, you cannot use it to modify the container; for example, - to insert items. -*/ - -/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the one-past-the-last occurrence of \a - value. If no such item is found, returns the position where the - item should be inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qUpperBound() can be used in conjunction with qLowerBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 - - \sa qLowerBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qUpperBound(const Container &container, const T &value) - \relates - - \overload - - This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of an occurrence of \a value. If there are - no occurrences of \a value, returns \a end. - - The items in the range [\a begin, \a end) must be sorted in - ascending order; see qSort(). - - If there are many occurrences of the same value, any one of them - could be returned. Use qLowerBound() or qUpperBound() if you need - finer control. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 - - This function requires the item type (in the example above, - QString) to implement \c operator<(). - - See the \l{#binaryFind example}{detailed - description} for an example usage. - - \sa qLowerBound(), qUpperBound(), {random access iterators} -*/ - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qBinaryFind(const Container &container, const T &value) - \relates - - \overload - - This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! - \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) - \relates - - Deletes all the items in the range [\a begin, \a end) using the - C++ \c delete operator. The item type must be a pointer type (for - example, \c{QWidget *}). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 - - Notice that qDeleteAll() doesn't remove the items from the - container; it merely calls \c delete on them. In the example - above, we call clear() on the container to remove the items. - - This function can also be used to delete items stored in - associative containers, such as QMap and QHash. Only the objects - stored in each container will be deleted by this function; objects - used as keys will not be deleted. - - \sa {forward iterators} -*/ - -/*! - \fn void qDeleteAll(const Container &c) - \relates - - \overload - - This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). -*/ - -/*! \fn LessThan qLess() - \relates - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 - - \sa {qGreater()}{qGreater()} -*/ - -/*! \fn LessThan qGreater() - \relates - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 - - \sa {qLess()}{qLess()} -*/ diff --git a/doc/src/qcache.qdoc b/doc/src/qcache.qdoc deleted file mode 100644 index 6c88ede..0000000 --- a/doc/src/qcache.qdoc +++ /dev/null @@ -1,244 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QCache - \brief The QCache class is a template class that provides a cache. - - \ingroup tools - \ingroup shared - \mainclass - \reentrant - - QCache\ defines a cache that stores objects of type T - associated with keys of type Key. For example, here's the - definition of a cache that stores objects of type Employee - associated with an integer key: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 - - Here's how to insert an object in the cache: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 - - The advantage of using QCache over some other key-based data - structure (such as QMap or QHash) is that QCache automatically - takes ownership of the objects that are inserted into the cache and - deletes them to make room for new objects, if necessary. When - inserting an object into the cache, you can specify a \e{cost}, - which should bear some approximate relationship to the amount of - memory taken by the object. When the sum of all objects' costs - (totalCost()) exceeds the cache's limit (maxCost()), QCache starts - deleting objects in the cache to keep under the limit, starting with - less recently accessed objects. - - By default, QCache's maxCost() is 100. You can specify a - different value in the QCache constructor: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 - - Each time you call insert(), you can specify a cost as third - argument (after the key and a pointer to the object to insert). - After the call, the inserted object is owned by the QCache, which - may delete it at any time to make room for other objects. - - To look up objects in the cache, use object() or - operator[](). This function looks up an object by its key, and - returns either a pointer to the cached object (which is owned by - the cache) or 0. - - If you want to remove an object from the cache for a particular key, - call remove(). This will also delete the object. If you want to - remove an object from the cache without the QCache deleting it, use - take(). - - \sa QPixmapCache, QHash, QMap -*/ - -/*! \fn QCache::QCache(int maxCost = 100) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost. -*/ - -/*! \fn QCache::~QCache() - - Destroys the cache. Deletes all the objects in the cache. -*/ - -/*! \fn int QCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost(), totalCost() -*/ - -/*! \fn void QCache::setMaxCost(int cost) - - Sets the maximum allowed total cost of the cache to \a cost. If - the current total cost is greater than \a cost, some objects are - deleted immediately. - - \sa maxCost(), totalCost() -*/ - -/*! \fn int QCache::totalCost() const - - Returns the total cost of the objects in the cache. - - This value is normally below maxCost(), but QCache makes an - exception for Qt's \l{implicitly shared} classes. If a cached - object shares its internal data with another instance, QCache may - keep the object lying around, possibly contributing to making - totalCost() larger than maxCost(). - - \sa setMaxCost() -*/ - -/*! \fn int QCache::size() const - - Returns the number of objects in the cache. - - \sa isEmpty() -*/ - -/*! \fn int QCache::count() const - - Same as size(). -*/ - -/*! \fn bool QCache::isEmpty() const - - Returns true if the cache contains no objects; otherwise - returns false. - - \sa size() -*/ - -/*! \fn QList QCache::keys() const - - Returns a list of the keys in the cache. -*/ - -/*! \fn void QCache::clear(); - - Deletes all the objects in the cache. - - \sa remove(), take() -*/ - - -/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1) - - Inserts \a object into the cache with key \a key and - associated cost \a cost. Any object with the same key already in - the cache will be removed. - - After this call, \a object is owned by the QCache and may be - deleted at any time. In particular, if \a cost is greater than - maxCost(), the object will be deleted immediately. - - The function returns true if the object was inserted into the - cache; otherwise it returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::object(const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - \warning The returned object is owned by QCache and may be - deleted at any time. - - \sa take(), remove() -*/ - -/*! \fn bool QCache::contains(const Key &key) const - - Returns true if the cache contains an object associated with key \a - key; otherwise returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::operator[](const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - This is the same as object(). - - \warning The returned object is owned by QCache and may be - deleted at any time. -*/ - -/*! \fn bool QCache::remove(const Key &key) - - Deletes the object associated with key \a key. Returns true if the - object was found in the cache; otherwise returns false. - - \sa take(), clear() -*/ - -/*! \fn T *QCache::take(const Key &key) - - Takes the object associated with key \a key out of the cache - without deleting it. Returns a pointer to the object taken out, or - 0 if the key does not exist in the cache. - - The ownership of the returned object is passed to the caller. - - \sa remove() -*/ - -/*! - \fn QCache::QCache(int maxCost, int dummy) - - Use QCache(int) instead. -*/ - -/*! - \fn T *QCache::find(const Key &key) const - - Use object() instead. -*/ diff --git a/doc/src/qcolormap.qdoc b/doc/src/qcolormap.qdoc deleted file mode 100644 index 95f7dc0..0000000 --- a/doc/src/qcolormap.qdoc +++ /dev/null @@ -1,152 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QColormap - \ingroup multimedia - - \brief The QColormap class maps device independent QColors to device - dependent pixel values. -*/ - -/*! \enum QColormap::Mode - - This enum describes how QColormap maps device independent RGB - values to device dependent pixel values. - - \value Direct Pixel values are derived directly from the RGB - values, also known as "True Color." - - \value Indexed Pixel values represent indexes into a vector of - available colors, i.e. QColormap uses the index of the color that - most closely matches an RGB value. - - \value Gray Similar to \c Indexed, pixel values represent a vector - of available gray tones. QColormap uses the index of the gray - tone that most closely matches the computed gray tone of an RGB - value. -*/ - -/*! - \fn QColormap QColormap::instance(int screen) - - Returns the colormap for the specified \a screen. If \a screen is - -1, this function returns the colormap for the default screen. -*/ - -/*! - \fn QColormap::QColormap(const QColormap &colormap) - - Constructs a copy of another \a colormap. -*/ - -/*! - \fn QColormap::~QColormap() - - Destroys the colormap. -*/ - -/*! - \fn int QColormap::size() const - - Returns the size of the colormap for \c Indexed and \c Gray modes; - Returns -1 for \c Direct mode. - - \sa colormap() -*/ - -/*! - \fn uint QColormap::pixel(const QColor &color) const - - Returns a device dependent pixel value for the \a color. - - \sa colorAt() -*/ - -/*! - \fn int QColormap::depth() const - - Returns the depth of the device. - - \sa size() -*/ - -/*! - \fn QColormap::Mode QColormap::mode() const - - Returns the mode of this colormap. - - \sa QColormap::Mode -*/ - -/*! - \fn const QColor QColormap::colorAt(uint pixel) const - - Returns a QColor for the \a pixel. - - \sa pixel() -*/ - -/*! - \fn const QVector QColormap::colormap() const - - Returns a vector of colors which represents the devices colormap - for \c Indexed and \c Gray modes. This function returns an empty - vector for \c Direct mode. - - \sa size() -*/ - -/*! \fn HPALETTE QColormap::hPal() - - This function is only available on Windows. - - Returns an handle to the HPALETTE used by this colormap. If no - HPALETTE is being used, this function returns zero. -*/ - -/*! \since 4.2 - - \fn QColormap &QColormap::operator=(const QColormap &colormap) - - Assigns the given \a colormap to \e this color map and returns - a reference to \e this color map. -*/ diff --git a/doc/src/qdesktopwidget.qdoc b/doc/src/qdesktopwidget.qdoc deleted file mode 100644 index 56a882d..0000000 --- a/doc/src/qdesktopwidget.qdoc +++ /dev/null @@ -1,266 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QDesktopWidget - \brief The QDesktopWidget class provides access to screen information on multi-head systems. - - \ingroup advanced - \ingroup desktop - \ingroup environment - \mainclass - - QApplication::desktop() function should be used to get an instance - of the QDesktopWidget. - - Systems with more than one graphics card and monitor can manage the - physical screen space available either as multiple desktops, or as a - large virtual desktop, which usually has the size of the bounding - rectangle of all the screens (see virtualDesktop). For an - application, one of the available screens is the primary screen, i.e. - the screen where the main widget resides (see primaryScreen). All - windows opened in the context of the application should be - constrained to the boundaries of the primary screen; for example, - it would be inconvenient if a dialog box popped up on a different - screen, or split over two screens. - - The QDesktopWidget provides information about the geometry of the - available screens with screenGeometry(). The number of screens - available is returned by screenCount, and the screenCountChanged - signal is emitted when screens are added or removed during runtime. - The screen number that a particular point or widget is located in - is returned by screenNumber(). - - Widgets provided by Qt use this class, for example, to place - tooltips, menus and dialog boxes according to the parent or - application widget. Applications can use this class to save window - positions, or to place child widgets and dialogs on one particular - screen. - - \img qdesktopwidget.png Managing Multiple Screens - - In the illustration above, Application One's primary screen is - screen 0, and App Two's primary screen is screen 1. - - \target multiple screens note - \note QDesktopWidget inherits the QWidget properties, width() and - height(), which specify the size of the desktop. However, for - desktops with multiple screens, the size of the desktop is the union - of all the screen sizes, so width() and height() should \e not be - used for computing the size of a widget to be placed on one of the - screens. The correct width and height values are obtained using - availableGeometry() or screenGeometry() for a particular screen. - - \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() -*/ - -/*! - \fn QDesktopWidget::QDesktopWidget() - - \internal - - Creates the desktop widget. - - If the system supports a virtual desktop, this widget will have - the size of the virtual desktop; otherwise this widget will have - the size of the primary screen. - - Instead of using QDesktopWidget directly, use QApplication::desktop(). -*/ - -/*! - \fn QDesktopWidget::~QDesktopWidget() - - \internal - - Destroys the desktop widget and frees any allocated resources. -*/ - -/*! - \fn int QDesktopWidget::numScreens() const - - Returns the number of available screens. - - \obsolete - - This function is deprecated. Use screenCount instead. - - \sa primaryScreen -*/ - -/*! - \fn QWidget *QDesktopWidget::screen(int screen) - - Returns a widget that represents the screen with index \a screen - (a value of -1 means the default screen). - - If the system uses a virtual desktop, the returned widget will - have the geometry of the entire virtual desktop; i.e., bounding - every \a screen. - - \sa primaryScreen, screenCount, virtualDesktop -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(int screen) const - - Returns the available geometry of the screen with index \a screen. What - is available will be subrect of screenGeometry() based on what the - platform decides is available (for example excludes the dock and menu bar - on Mac OS X, or the task bar on Windows). The default screen is used if - \a screen is -1. - - \sa screenNumber(), screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const - \overload - - Returns the available geometry of the screen which contains \a widget. - - \sa screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const - \overload - - Returns the available geometry of the screen which contains \a p. - - \sa screenGeometry() -*/ - - -/*! - \fn const QRect QDesktopWidget::screenGeometry(int screen) const - - Returns the geometry of the screen with index \a screen. The default - screen is used if \a screen is -1. - - \sa screenNumber() -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const - \overload - - Returns the geometry of the screen which contains \a widget. -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const - \overload - - Returns the geometry of the screen which contains \a p. -*/ - - -/*! - \fn int QDesktopWidget::screenNumber(const QWidget *widget) const - - Returns the index of the screen that contains the largest - part of \a widget, or -1 if the widget not on a screen. - - \sa primaryScreen -*/ - -/*! - \fn int QDesktopWidget::screenNumber(const QPoint &point) const - - \overload - Returns the index of the screen that contains the \a point, or the - screen which is the shortest distance from the \a point. - - \sa primaryScreen -*/ - -/*! - \fn void QDesktopWidget::resizeEvent(QResizeEvent *event) - \reimp -*/ - -/*! - \fn void QDesktopWidget::resized(int screen) - - This signal is emitted when the size of \a screen changes. -*/ - -/*! - \fn void QDesktopWidget::workAreaResized(int screen) - - This signal is emitted when the work area available on \a screen changes. -*/ - -/*! - \property QDesktopWidget::screenCount - \brief the number of screens currently available on the system. - - \since 4.6 - - \sa screenCountChanged() -*/ - -/*! - \property QDesktopWidget::primaryScreen - \brief the index of the screen that is configured to be the primary screen - on the system. -*/ - -/*! - \property QDesktopWidget::virtualDesktop - - \brief if the system manages the available screens in a virtual desktop. - - For virtual desktops, screen() will always return the same widget. - The size of the virtual desktop is the size of this desktop - widget. -*/ - -/*! - \fn void QDesktopWidget::screenCountChanged(int newCount) - - \since 4.6 - - This signal is emitted when the number of screens changes to \a newCount. - - \sa screenCount -*/ diff --git a/doc/src/qiterator.qdoc b/doc/src/qiterator.qdoc deleted file mode 100644 index 416b4bc..0000000 --- a/doc/src/qiterator.qdoc +++ /dev/null @@ -1,1431 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QListIterator - \inmodule QtCore - - \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, modify, and remove items without - using iterators. - - QListIterator\ allows you to iterate over a QList\ (or a - QQueue\). If you want to modify the list as you iterate over - it, use QMutableListIterator\ instead. - - The QListIterator constructor takes a QList as argument. After - construction, the iterator is located at the very beginning of - the list (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QListIterator is active, the QListIterator will - continue iterating over the original list, ignoring the modified - copy. - - \sa QMutableListIterator, QList::const_iterator -*/ - -/*! - \class QLinkedListIterator - \inmodule QtCore - - \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QLinkedListIterator\ allows you to iterate over a - QLinkedList\. If you want to modify the list as you iterate - over it, use QMutableLinkedListIterator\ instead. - - The QLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QLinkedListIterator is active, the - QLinkedListIterator will continue iterating over the original - list, ignoring the modified copy. - - \sa QMutableLinkedListIterator, QLinkedList::const_iterator -*/ - -/*! - \class QVectorIterator - \inmodule QtCore - \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QVectorIterator\ allows you to iterate over a QVector\ - (or a QStack\). If you want to modify the vector as you - iterate over it, use QMutableVectorIterator\ instead. - - The QVectorIterator constructor takes a QVector as argument. - After construction, the iterator is located at the very beginning - of the vector (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same vector. If the vector - is modified while a QVectorIterator is active, the QVectorIterator - will continue iterating over the original vector, ignoring the - modified copy. - - \sa QMutableVectorIterator, QVector::const_iterator -*/ - -/*! - \class QSetIterator - \inmodule QtCore - \brief The QSetIterator class provides a Java-style const iterator for QSet. - - QSet supports both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QSetIterator\ allows you to iterate over a QSet\. If you - want to modify the set as you iterate over it, use - QMutableSetIterator\ instead. - - The constructor takes a QSet as argument. After construction, the - iterator is located at the very beginning of the set (before - the first item). Here's how to iterate over all the elements - sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same set. If the set - is modified while a QSetIterator is active, the QSetIterator - will continue iterating over the original set, ignoring the - modified copy. - - \sa QMutableSetIterator, QSet::const_iterator -*/ - -/*! - \class QMutableListIterator - \inmodule QtCore - - \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableListIterator\ allows you to iterate over a QList\ - (or a QQueue\) and modify the list. If you don't want to - modify the list (or have a const QList), use the slightly faster - QListIterator\ instead. - - The QMutableListIterator constructor takes a QList as argument. - After construction, the iterator is located at the very beginning - of the list (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QListIterator, QList::iterator -*/ - -/*! - \class QMutableLinkedListIterator - \inmodule QtCore - - \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QMutableLinkedListIterator\ allows you to iterate over a - QLinkedList\ and modify the list. If you don't want to modify - the list (or have a const QLinkedList), use the slightly faster - QLinkedListIterator\ instead. - - The QMutableLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QLinkedListIterator, QLinkedList::iterator -*/ - -/*! - \class QMutableVectorIterator - \inmodule QtCore - - \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableVectorIterator\ allows you to iterate over a - QVector\ and modify the vector. If you don't want to modify - the vector (or have a const QVector), use the slightly faster - QVectorIterator\ instead. - - The QMutableVectorIterator constructor takes a QVector as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the vector, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the vector, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 - - The example traverses a vector, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given vector at any - time. Furthermore, no changes should be done directly to the - vector while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QVectorIterator, QVector::iterator -*/ - -/*! - \class QMutableSetIterator - \inmodule QtCore - \since 4.2 - - \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. - - QSet has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableSetIterator\ allows you to iterate over a QSet\ - and remove items from the set as you iterate. If you don't want - to modify the set (or have a const QSet), use the slightly faster - QSetIterator\ instead. - - The QMutableSetIterator constructor takes a QSet as argument. - After construction, the iterator is located at the very beginning - of the set (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 - - If you want to remove items as you iterate over the set, use - remove(). - - Only one mutable iterator can be active on a given set at any - time. Furthermore, no changes should be done directly to the set - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QSetIterator, QSet::iterator -*/ - -/*! - \fn QListIterator::QListIterator(const QList &list) - \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList &list) - \fn QMutableListIterator::QMutableListIterator(QList &list) - \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList &list) - - Constructs an iterator for traversing \a list. The iterator is - set to be at the front of the list (before the first item). - - \sa operator=() -*/ - -/*! - \fn QVectorIterator::QVectorIterator(const QVector &vector) - \fn QMutableVectorIterator::QMutableVectorIterator(QVector &vector) - - Constructs an iterator for traversing \a vector. The iterator is - set to be at the front of the vector (before the first item). - - \sa operator=() -*/ - -/*! - \fn QSetIterator::QSetIterator(const QSet &set) - \fn QMutableSetIterator::QMutableSetIterator(QSet &set) - - Constructs an iterator for traversing \a set. The iterator is - set to be at the front of the set (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableListIterator::~QMutableListIterator() - \fn QMutableLinkedListIterator::~QMutableLinkedListIterator() - \fn QMutableVectorIterator::~QMutableVectorIterator() - \fn QMutableSetIterator::~QMutableSetIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList &list) - \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList &list) - \fn QListIterator &QListIterator::operator=(const QList &list) - \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList &list) - - Makes the iterator operate on \a list. The iterator is set to be - at the front of the list (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector &vector) - \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector &vector) - - Makes the iterator operate on \a vector. The iterator is set to be - at the front of the vector (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QSetIterator &QSetIterator::operator=(const QSet &set) - \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet &set) - - Makes the iterator operate on \a set. The iterator is set to be - at the front of the set (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QListIterator::toFront() - \fn void QLinkedListIterator::toFront() - \fn void QVectorIterator::toFront() - \fn void QSetIterator::toFront() - \fn void QMutableListIterator::toFront() - \fn void QMutableLinkedListIterator::toFront() - \fn void QMutableVectorIterator::toFront() - \fn void QMutableSetIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QListIterator::toBack() - \fn void QLinkedListIterator::toBack() - \fn void QVectorIterator::toBack() - \fn void QSetIterator::toBack() - \fn void QMutableListIterator::toBack() - \fn void QMutableLinkedListIterator::toBack() - \fn void QMutableVectorIterator::toBack() - \fn void QMutableSetIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QListIterator::hasNext() const - \fn bool QLinkedListIterator::hasNext() const - \fn bool QVectorIterator::hasNext() const - \fn bool QSetIterator::hasNext() const - \fn bool QMutableListIterator::hasNext() const - \fn bool QMutableLinkedListIterator::hasNext() const - \fn bool QMutableVectorIterator::hasNext() const - \fn bool QMutableSetIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn const T &QListIterator::next() - \fn const T &QLinkedListIterator::next() - \fn const T &QVectorIterator::next() - \fn const T &QSetIterator::next() - \fn const T &QMutableSetIterator::next() - - Returns the next item and advances the iterator by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn T &QMutableListIterator::next() - \fn T &QMutableLinkedListIterator::next() - \fn T &QMutableVectorIterator::next() - - Returns a reference to the next item, and advances the iterator - by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn const T &QListIterator::peekNext() const - \fn const T &QLinkedListIterator::peekNext() const - \fn const T &QVectorIterator::peekNext() const - \fn const T &QSetIterator::peekNext() const - \fn const T &QMutableSetIterator::peekNext() const - - Returns the next item without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn T &QMutableListIterator::peekNext() const - \fn T &QMutableLinkedListIterator::peekNext() const - \fn T &QMutableVectorIterator::peekNext() const - - Returns a reference to the next item, without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QListIterator::hasPrevious() const - \fn bool QLinkedListIterator::hasPrevious() const - \fn bool QVectorIterator::hasPrevious() const - \fn bool QSetIterator::hasPrevious() const - \fn bool QMutableListIterator::hasPrevious() const - \fn bool QMutableLinkedListIterator::hasPrevious() const - \fn bool QMutableVectorIterator::hasPrevious() const - \fn bool QMutableSetIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn const T &QListIterator::previous() - \fn const T &QLinkedListIterator::previous() - \fn const T &QVectorIterator::previous() - \fn const T &QSetIterator::previous() - \fn const T &QMutableSetIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn T &QMutableListIterator::previous() - \fn T &QMutableLinkedListIterator::previous() - \fn T &QMutableVectorIterator::previous() - - Returns a reference to the previous item and moves the iterator - back by one position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn const T &QListIterator::peekPrevious() const - \fn const T &QLinkedListIterator::peekPrevious() const - \fn const T &QVectorIterator::peekPrevious() const - \fn const T &QSetIterator::peekPrevious() const - \fn const T &QMutableSetIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn T &QMutableListIterator::peekPrevious() const - \fn T &QMutableLinkedListIterator::peekPrevious() const - \fn T &QMutableVectorIterator::peekPrevious() const - - Returns a reference to the previous item, without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn bool QListIterator::findNext(const T &value) - \fn bool QLinkedListIterator::findNext(const T &value) - \fn bool QVectorIterator::findNext(const T &value) - \fn bool QSetIterator::findNext(const T &value) - \fn bool QMutableListIterator::findNext(const T &value) - \fn bool QMutableLinkedListIterator::findNext(const T &value) - \fn bool QMutableVectorIterator::findNext(const T &value) - \fn bool QMutableSetIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if \a value is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QListIterator::findPrevious(const T &value) - \fn bool QLinkedListIterator::findPrevious(const T &value) - \fn bool QVectorIterator::findPrevious(const T &value) - \fn bool QSetIterator::findPrevious(const T &value) - \fn bool QMutableListIterator::findPrevious(const T &value) - \fn bool QMutableLinkedListIterator::findPrevious(const T &value) - \fn bool QMutableVectorIterator::findPrevious(const T &value) - \fn bool QMutableSetIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if \a value is found; otherwise returns - false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableLinkedListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableVectorIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableSetIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 - - \sa value() -*/ - -/*! \fn void QMutableListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableVectorIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 - - \sa value(), remove(), insert() -*/ - -/*! \fn const T &QMutableListIterator::value() const - \fn const T &QMutableLinkedListIterator::value() const - \fn const T &QMutableVectorIterator::value() const - \fn const T &QMutableSetIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is equivalent to - peekPrevious(). After a call to previous() or findPrevious(), value() is - equivalent to peekNext(). -*/ - -/*! - \fn T &QMutableListIterator::value() - \fn T &QMutableLinkedListIterator::value() - \fn T &QMutableVectorIterator::value() - \overload - - Returns a non-const reference to the value of the last item that - was jumped over using one of the traversal functions. -*/ - -/*! \fn void QMutableListIterator::insert(const T &value) - \fn void QMutableLinkedListIterator::insert(const T &value) - \fn void QMutableVectorIterator::insert(const T &value) - - Inserts \a value at the current iterator position. After the - call, the iterator is located just after the inserted item. - - \sa remove(), setValue() -*/ - -/*! - \class QMapIterator - \inmodule QtCore - - \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMapIterator\ allows you to iterate over a QMap (or a - QMultiMap). If you want to modify the map as you iterate over - it, use QMutableMapIterator instead. - - The QMapIterator constructor takes a QMap as argument. After - construction, the iterator is located at the very beginning of - the map (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 - - Multiple iterators can be used on the same map. If the map is - modified while a QMapIterator is active, the QMapIterator will - continue iterating over the original map, ignoring the modified - copy. - - \sa QMutableMapIterator, QMap::const_iterator -*/ - -/*! - \class QHashIterator - \inmodule QtCore - - \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QHashIterator\ allows you to iterate over a QHash (or a - QMultiHash). If you want to modify the hash as you iterate over - it, use QMutableHashIterator instead. - - The QHashIterator constructor takes a QHash as argument. After - construction, the iterator is located at the very beginning of - the hash (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 - - Multiple iterators can be used on the same hash. If the hash is - modified while a QHashIterator is active, the QHashIterator will - continue iterating over the original hash, ignoring the modified - copy. - - \sa QMutableHashIterator, QHash::const_iterator -*/ - -/*! - \class QMutableMapIterator - \inmodule QtCore - - \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableMapIterator\ allows you to iterate over a QMap - (or a QMultiMap) and modify the map. If you don't want to modify - the map (or have a const QMap), use the slightly faster - QMapIterator instead. - - The QMutableMapIterator constructor takes a QMap as argument. - After construction, the iterator is located at the very beginning - of the map (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 - - If you want to remove items as you iterate over the map, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given map at any - time. Furthermore, no changes should be done directly to the map - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QMapIterator, QMap::iterator -*/ - -/*! - \class QMutableHashIterator - \inmodule QtCore - - \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableHashIterator\ allows you to iterate over a QHash - (or a QMultiHash) and modify the hash. If you don't want to modify - the hash (or have a const QHash), use the slightly faster - QHashIterator instead. - - The QMutableHashIterator constructor takes a QHash as argument. - After construction, the iterator is located at the very beginning - of the hash (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 - - If you want to remove items as you iterate over the hash, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given hash at any - time. Furthermore, no changes should be done directly to the hash - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QHashIterator, QHash::iterator -*/ - -/*! \fn QMapIterator::QMapIterator(const QMap &map) - \fn QMutableMapIterator::QMutableMapIterator(QMap &map) - - Constructs an iterator for traversing \a map. The iterator is set - to be at the front of the map (before the first item). - - \sa operator=() -*/ - -/*! \fn QHashIterator::QHashIterator(const QHash &hash) - \fn QMutableHashIterator::QMutableHashIterator(QHash &hash) - - Constructs an iterator for traversing \a hash. The iterator is - set to be at the front of the hash (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableMapIterator::~QMutableMapIterator() - \fn QMutableHashIterator::~QMutableHashIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMapIterator &QMapIterator::operator=(const QMap &map) - \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap &map) - - Makes the iterator operate on \a map. The iterator is set to be - at the front of the map (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QHashIterator &QHashIterator::operator=(const QHash &hash) - \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash &hash) - - Makes the iterator operate on \a hash. The iterator is set to be - at the front of the hash (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QMapIterator::toFront() - \fn void QHashIterator::toFront() - \fn void QMutableMapIterator::toFront() - \fn void QMutableHashIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QMapIterator::toBack() - \fn void QHashIterator::toBack() - \fn void QMutableMapIterator::toBack() - \fn void QMutableHashIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QMapIterator::hasNext() const - \fn bool QHashIterator::hasNext() const - \fn bool QMutableMapIterator::hasNext() const - \fn bool QMutableHashIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::next() - \fn QHashIterator::Item QHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::next() - \fn QMutableHashIterator::Item QMutableHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekNext() const - \fn QHashIterator::Item QHashIterator::peekNext() const - - Returns the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const - - Returns a reference to the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QMapIterator::hasPrevious() const - \fn bool QHashIterator::hasPrevious() const - \fn bool QMutableMapIterator::hasPrevious() const - \fn bool QMutableHashIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::previous() - \fn QHashIterator::Item QHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous() - \fn QMutableHashIterator::Item QMutableHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const - \fn QHashIterator::Item QHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn const T &QMapIterator::value() const - \fn const T &QHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key() -*/ - -/*! - \fn const T &QMutableMapIterator::value() const - \fn const T &QMutableHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key(), setValue() -*/ - -/*! - \fn T &QMutableMapIterator::value() - \fn T &QMutableHashIterator::value() - \overload - - Returns a non-const reference to the value of - the last item that was jumped over using one - of the traversal functions. -*/ - -/*! \fn const Key &QMapIterator::key() const - \fn const Key &QHashIterator::key() const - \fn const Key &QMutableMapIterator::key() const - \fn const Key &QMutableHashIterator::key() const - - Returns the key of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), key() is - equivalent to peekPrevious().key(). After a call to previous() or - findPrevious(), key() is equivalent to peekNext().key(). - - \sa value() -*/ - -/*! \fn bool QMapIterator::findNext(const T &value) - \fn bool QHashIterator::findNext(const T &value) - \fn bool QMutableMapIterator::findNext(const T &value) - \fn bool QMutableHashIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QMapIterator::findPrevious(const T &value) - \fn bool QHashIterator::findPrevious(const T &value) - \fn bool QMutableMapIterator::findPrevious(const T &value) - \fn bool QMutableHashIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableMapIterator::remove() - \fn void QMutableHashIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - \sa setValue() -*/ - -/*! \fn void QMutableMapIterator::setValue(const T &value) - \fn void QMutableHashIterator::setValue(const T &value) - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - \sa key(), value(), remove() -*/ diff --git a/doc/src/qpagesetupdialog.qdoc b/doc/src/qpagesetupdialog.qdoc deleted file mode 100644 index 7f0b09e..0000000 --- a/doc/src/qpagesetupdialog.qdoc +++ /dev/null @@ -1,84 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPageSetupDialog - - \brief The QPageSetupDialog class provides a configuration dialog - for the page-related options on a printer. - - On Windows and Mac OS X the page setup dialog is implemented using - the native page setup dialogs. - - Note that on Windows and Mac OS X custom paper sizes won't be - reflected in the native page setup dialogs. Additionally, custom - page margins set on a QPrinter won't show in the native Mac OS X - page setup dialog. - - \sa QPrinter, QPrintDialog -*/ - - -/*! - \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) - - Constructs a page setup dialog that configures \a printer with \a - parent as the parent widget. -*/ - -/*! - \since 4.5 - - \fn QPageSetupDialog::QPageSetupDialog(QWidget *parent) - - Constructs a page setup dialog that configures a default-constructed - QPrinter with \a parent as the parent widget. - - \sa printer() -*/ - -/*! - \fn QPrinter *QPageSetupDialog::printer() - - Returns the printer that was passed to the QPageSetupDialog - constructor. -*/ - diff --git a/doc/src/qpaintdevice.qdoc b/doc/src/qpaintdevice.qdoc deleted file mode 100644 index 0f4e9a0..0000000 --- a/doc/src/qpaintdevice.qdoc +++ /dev/null @@ -1,289 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPaintDevice - \brief The QPaintDevice class is the base class of objects that - can be painted. - - \ingroup multimedia - - A paint device is an abstraction of a two-dimensional space that - can be drawn using a QPainter. Its default coordinate system has - its origin located at the top-left position. X increases to the - right and Y increases downwards. The unit is one pixel. - - The drawing capabilities of QPaintDevice are currently implemented - by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and - QPrinter subclasses. - - To implement support for a new backend, you must derive from - QPaintDevice and reimplement the virtual paintEngine() function to - tell QPainter which paint engine should be used to draw on this - particular device. Note that you also must create a corresponding - paint engine to be able to draw on the device, i.e derive from - QPaintEngine and reimplement its virtual functions. - - \warning Qt requires that a QApplication object exists before - any paint devices can be created. Paint devices access window - system resources, and these resources are not initialized before - an application object is created. - - The QPaintDevice class provides several functions returning the - various device metrics: The depth() function returns its bit depth - (number of bit planes). The height() function returns its height - in default coordinate system units (e.g. pixels for QPixmap and - QWidget) while heightMM() returns the height of the device in - millimeters. Similiarily, the width() and widthMM() functions - return the width of the device in default coordinate system units - and in millimeters, respectively. Alternatively, the protected - metric() function can be used to retrieve the metric information - by specifying the desired PaintDeviceMetric as argument. - - The logicalDpiX() and logicalDpiY() functions return the - horizontal and vertical resolution of the device in dots per - inch. The physicalDpiX() and physicalDpiY() functions also return - the resolution of the device in dots per inch, but note that if - the logical and vertical resolution differ, the corresponding - QPaintEngine must handle the mapping. Finally, the numColors() - function returns the number of different colors available for the - paint device. - - \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint - System} -*/ - -/*! - \enum QPaintDevice::PaintDeviceMetric - - Describes the various metrics of a paint device. - - \value PdmWidth The width of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also width(). - - \value PdmHeight The height of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also height(). - - \value PdmWidthMM The width of the paint device in millimeters. See - also widthMM(). - - \value PdmHeightMM The height of the paint device in millimeters. See - also heightMM(). - - \value PdmNumColors The number of different colors available for - the paint device. See also numColors(). - - \value PdmDepth The bit depth (number of bit planes) of the paint - device. See also depth(). - - \value PdmDpiX The horizontal resolution of the device in dots per - inch. See also logicalDpiX(). - - \value PdmDpiY The vertical resolution of the device in dots per inch. See - also logicalDpiY(). - - \value PdmPhysicalDpiX The horizontal resolution of the device in - dots per inch. See also physicalDpiX(). - - \value PdmPhysicalDpiY The vertical resolution of the device in - dots per inch. See also physicalDpiY(). - - \sa metric() -*/ - -/*! - \fn QPaintDevice::QPaintDevice() - - Constructs a paint device. This constructor can be invoked only from - subclasses of QPaintDevice. -*/ - -/*! - \fn QPaintDevice::~QPaintDevice() - - Destroys the paint device and frees window system resources. -*/ - -/*! - \fn int QPaintDevice::devType() const - - \internal - - Returns the device type identifier, which is QInternal::Widget - if the device is a QWidget, QInternal::Pixmap if it's a - QPixmap, QInternal::Printer if it's a QPrinter, - QInternal::Picture if it's a QPicture, or - QInternal::UnknownDevice in other cases. -*/ - -/*! - \fn bool QPaintDevice::paintingActive() const - - Returns true if the device is currently being painted on, i.e. someone has - called QPainter::begin() but not yet called QPainter::end() for - this device; otherwise returns false. - - \sa QPainter::isActive() -*/ - -/*! - \fn QPaintEngine *QPaintDevice::paintEngine() const - - Returns a pointer to the paint engine used for drawing on the - device. -*/ - -/*! - \fn int QPaintDevice::metric(PaintDeviceMetric metric) const - - Returns the metric information for the given paint device \a metric. - - \sa PaintDeviceMetric -*/ - -/*! - \fn int QPaintDevice::width() const - - Returns the width of the paint device in default coordinate system - units (e.g. pixels for QPixmap and QWidget). - - \sa widthMM() -*/ - -/*! - \fn int QPaintDevice::height() const - - Returns the height of the paint device in default coordinate - system units (e.g. pixels for QPixmap and QWidget). - - \sa heightMM() -*/ - -/*! - \fn int QPaintDevice::widthMM() const - - Returns the width of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa width() -*/ - -/*! - \fn int QPaintDevice::heightMM() const - - Returns the height of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa height() -*/ - -/*! - \fn int QPaintDevice::numColors() const - - Returns the number of different colors available for the paint - device. Since this value is an int, it will not be sufficient to represent - the number of colors on 32 bit displays, in this case INT_MAX is - returned instead. -*/ - -/*! - \fn int QPaintDevice::depth() const - - Returns the bit depth (number of bit planes) of the paint device. -*/ - -/*! - \fn int QPaintDevice::logicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from widthMM(). - - Note that if the logicalDpiX() doesn't equal the physicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiY(), physicalDpiX() -*/ - -/*! - \fn int QPaintDevice::logicalDpiY() const - - Returns the vertical resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from heightMM(). - - Note that if the logicalDpiY() doesn't equal the physicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiX(), physicalDpiY() -*/ - -/*! - \fn int QPaintDevice::physicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiX() doesn't equal the logicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiY(), logicalDpiX() -*/ - -/*! - \fn int QPaintDevice::physicalDpiY() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiY() doesn't equal the logicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiX(), logicalDpiY() -*/ diff --git a/doc/src/qpair.qdoc b/doc/src/qpair.qdoc deleted file mode 100644 index 6d8a0f9..0000000 --- a/doc/src/qpair.qdoc +++ /dev/null @@ -1,229 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPair - \brief The QPair class is a template class that stores a pair of items. - - \ingroup tools - - QPair\ can be used in your application if the STL \c - pair type is not available. It stores one value of type T1 and - one value of type T2. It can be used as a return value for a - function that needs to return two values, or as the value type of - a \l{generic container}. - - Here's an example of a QPair that stores one QString and one \c - double value: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 - - The components are accessible as public data members called \l - first and \l second. For example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 - - QPair's template data types (T1 and T2) must be \l{assignable - data types}. You cannot, for example, store a QWidget as a value; - instead, store a QWidget *. A few functions have additional - requirements; these requirements are documented on a per-function - basis. - - \sa {Generic Containers} -*/ - -/*! \typedef QPair::first_type - - The type of the first element in the pair (T1). - - \sa first -*/ - -/*! \typedef QPair::second_type - - The type of the second element in the pair (T2). - - \sa second -*/ - -/*! \variable QPair::first - - The first element in the pair. -*/ - -/*! \variable QPair::second - - The second element in the pair. -*/ - -/*! \fn QPair::QPair() - - Constructs an empty pair. The \c first and \c second elements are - initialized with \l{default-constructed values}. -*/ - -/*! - \fn QPair::QPair(const T1 &value1, const T2 &value2) - - Constructs a pair and initializes the \c first element with \a - value1 and the \c second element with \a value2. - - \sa qMakePair() -*/ - -/*! - \fn QPair &QPair::operator=(const QPair &other) - - Assigns \a other to this pair. -*/ - -/*! \fn bool operator==(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is equal to \a p2; otherwise returns false. - Two pairs compare equal if their \c first data members compare - equal and if their \c second data members compare equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator!=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is not equal to \a p2; otherwise returns - false. Two pairs compare as not equal if their \c first data - members are not equal or if their \c second data members are not - equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator<(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is less than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is greater than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator<=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is less than or equal to \a p2; otherwise - returns false. The comparison is done on the \c first members of - \a p1 and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is greater than or equal to \a p2; - otherwise returns false. The comparison is done on the \c first - members of \a p1 and \a p2; if they compare equal, the \c second - members are compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! - \fn QPair qMakePair(const T1 &value1, const T2 &value2) - - \relates QPair - - Returns a QPair\ that contains \a value1 and \a value2. - Example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 - - This is equivalent to QPair(\a value1, \a value2), but - usually requires less typing. -*/ - -/*! \fn QDataStream &operator>>(QDataStream &in, QPair &pair) - - \relates QPair - - Reads a pair from stream \a in into \a pair. - - This function requires the T1 and T2 types to implement \c operator>>(). - - \sa {Format of the QDataStream operators} -*/ - -/*! \fn QDataStream &operator<<(QDataStream &out, const QPair &pair) - - \relates QPair - - Writes the pair \a pair to stream \a out. - - This function requires the T1 and T2 types to implement \c operator<<(). - - \sa {Format of the QDataStream operators} -*/ diff --git a/doc/src/qpatternistdummy.cpp b/doc/src/qpatternistdummy.cpp deleted file mode 100644 index a690184..0000000 --- a/doc/src/qpatternistdummy.cpp +++ /dev/null @@ -1,1010 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - - This file exists only to make internal all the classes you see - below. they are all in the QPatternist namespace, but they don't - have qdoc documentation because they are all declared in xxx_p.h files. Without these \internal declarations, the class names - appear on the Inheritance Hierarchy page, which is bad because - clicking on them brings up the "File not found" page. - */ - -#include "qitem_p.h" -#include "qbuiltintypes_p.h" -#include "qitem_p.h" -#include "qschematypefactory_p.h" -#include "qxmlname.h" -#include "qatomictype_p.h" - -QT_BEGIN_NAMESPACE - -using namespace QPatternist; - -/*! - \class AtomicCaster - \internal - */ - -/*! - \class AtomicComparator - \internal - */ - -/*! - \class AtomicMathematician - \internal - */ - -/*! - \class AtomicValue - \internal - */ - -/*! - \class AbstractDateTime - \internal - */ - -/*! - \class AbstractDuration - \internal - */ - -/*! - \class AbstractFloatComparator - \internal - */ - -/*! - \class AtomicString - \internal - */ - -/*! - \class Base64Binary - \internal - */ - -/*! - \class FunctionCall - \internal - */ - -/*! - \class AddingAggregate - \internal - */ - -/*! - \class AdjustTimezone - \internal - */ - -/*! - \class Aggregator - \internal - */ - -/*! - \class ComparesCaseAware - \internal - */ - -/*! - \class EncodeString - \internal - */ - -/*! - \class ExtractFromDateTimeFN - \internal - */ - -/*! - \class ExtractFromDurationFN - \internal - */ - -/*! - \class FunctionFactory - \internal - */ - -/*! - \class Numeric - \internal - */ - -/*! - \class ReportContext - \internal - */ - -/*! - \class AbstractFunctionFactory - \internal - */ - -/*! - \class DynamicContext - \internal - */ - -/*! - \class IdFN - \internal - */ - -/*! - \class IntegerType - \internal - */ - -/*! - \class NamespaceResolver - \internal - */ - -/*! - \class PatternPlatform - \internal - */ - -/*! \class DocumentProjector - \internal */ -/*! \class NodeBuilder - \internal */ -/*! \class AccelTreeBuilder - \internal */ -/*! \class OutputValidator - \internal */ -/*! \class NetworkLoop - \internal */ -/*! \class QIODeviceDelegate - \internal */ -/*! \class URILoader - \internal */ -/*! \class AbsFN - \internal */ -/*! \class AbstractDateTimeComparator - \internal */ -/*! \class AbstractDateTimeMathematician - \internal */ -/*! \class AbstractDateTimeToDateCaster - \internal */ -/*! \class AbstractDateTimeToDateTimeCaster - \internal */ -/*! \class AbstractDateTimeToGDayCaster - \internal */ -/*! \class AbstractDateTimeToGMonthCaster - \internal */ -/*! \class AbstractDateTimeToGMonthDayCaster - \internal */ -/*! \class AbstractDateTimeToGYearCaster - \internal */ -/*! \class AbstractDateTimeToGYearMonthCaster - \internal */ -/*! \class AbstractDateTimeToTimeCaster - \internal */ -/*! \class AbstractDurationComparator - \internal */ -/*! \class AbstractDurationToDayTimeDurationCaster - \internal */ -/*! \class AbstractDurationToDurationCaster - \internal */ -/*! \class AbstractDurationToYearMonthDurationCaster - \internal */ -/*! \class AbstractFloat - \internal */ -/*! \class AbstractFloatMathematician - \internal */ -/*! \class AbstractFloatSortComparator - \internal */ -/*! \class ConstructorFunctionsFactory - \internal */ -/*! \class XPath10CoreFunctions - \internal */ -/*! \class XPath20CoreFunctions - \internal */ -/*! \class AdjustDateTimeToTimezoneFN - \internal */ -/*! \class AdjustDateToTimezoneFN - \internal */ -/*! \class AdjustTimeToTimezoneFN - \internal */ -/*! \class AnyToDerivedStringCaster - \internal */ -/*! \class AnyURI - \internal */ -/*! \class Atomizer - \internal */ -/*! \class AvgFN - \internal */ -/*! \class Base64BinaryComparatorLocator - \internal */ -/*! \class Base64BinaryToHexBinaryCaster - \internal */ -/*! \class Base64BinaryType - \internal */ -/*! \class BaseURIFN - \internal */ -/*! \class BinaryDataComparator - \internal */ -/*! \class Boolean - \internal */ -/*! \class BooleanComparator - \internal */ -/*! \class BooleanComparatorLocator - \internal */ -/*! \class BooleanFN - \internal */ -/*! \class BooleanToAbstractFloatCaster - \internal */ -/*! \class BooleanToDecimalCaster - \internal */ -/*! \class BooleanToDerivedIntegerCaster - \internal */ -/*! \class BooleanToIntegerCaster - \internal */ -/*! \class BooleanType - \internal */ -/*! \class BuiltinNodeType - \internal */ -/*! \class CardinalityVerifier - \internal */ -/*! \class CaseInsensitiveStringComparator - \internal */ -/*! \class CeilingFN - \internal */ -/*! \class CodepointEqualFN - \internal */ -/*! \class CodepointsToStringFN - \internal */ -/*! \class CollectionFN - \internal */ -/*! \class CompareFN - \internal */ -/*! \class ComparingAggregator - \internal */ -/*! \class ConcatFN - \internal */ -/*! \class ContainsFN - \internal */ -/*! \class CountFN - \internal */ -/*! \class CurrentDateFN - \internal */ -/*! \class CurrentDateTimeFN - \internal */ -/*! \class CurrentTimeFN - \internal */ -/*! \class Date - \internal */ -/*! \class DateComparatorLocator - \internal */ -/*! \class DateMathematicianLocator - \internal */ -/*! \class DateTime - \internal */ -/*! \class DateTimeComparatorLocator - \internal */ -/*! \class DateTimeDurationMathematician - \internal */ -/*! \class DateTimeFN - \internal */ -/*! \class DateTimeMathematicianLocator - \internal */ -/*! \class DateTimeType - \internal */ -/*! \class DateType - \internal */ -/*! \class DayFromAbstractDateTimeFN - \internal */ -/*! \class DayTimeDuration - \internal */ -/*! \class DayTimeDurationComparatorLocator - \internal */ -/*! \class DayTimeDurationMathematicianLocator - \internal */ -/*! \class DayTimeDurationType - \internal */ -/*! \class DaysFromDurationFN - \internal */ -/*! \class Decimal - \internal */ -/*! \class DecimalComparator - \internal */ -/*! \class DecimalComparatorLocator - \internal */ -/*! \class DecimalMathematician - \internal */ -/*! \class DecimalMathematicianLocator - \internal */ -/*! \class DecimalType - \internal */ -/*! \class DeduplicateIterator - \internal */ -/*! \class DeepEqualFN - \internal */ -/*! \class DefaultCollationFN - \internal */ -/*! \class DerivedInteger - \internal */ -/*! \class DerivedString - \internal */ -/*! \class DistinctValuesFN - \internal */ -/*! \class DocAvailableFN - \internal */ -/*! \class DocFN - \internal */ -/*! \class DocumentURIFN - \internal */ -/*! \class DoubleComparatorLocator - \internal */ -/*! \class DoubleMathematicianLocator - \internal */ -/*! \class DoubleType - \internal */ -/*! \class Duration - \internal */ -/*! \class DurationComparatorLocator - \internal */ -/*! \class DurationDurationDivisor - \internal */ -/*! \class DurationDurationMathematician - \internal */ -/*! \class DurationNumericMathematician - \internal */ -/*! \class DurationType - \internal */ -/*! \class DelegatingDynamicContext - \internal */ -/*! \class Focus - \internal */ -/*! \class ReceiverDynamicContext - \internal */ -/*! \class EmptyIterator - \internal */ -/*! \class EncodeForURIFN - \internal */ -/*! \class EndsWithFN - \internal */ -/*! \class ErrorFN - \internal */ -/*! \class EscapeHtmlURIFN - \internal */ -/*! \class EvaluationCache - \internal */ -/*! \class Existence - \internal */ -/*! \class ExpressionVisitor - \internal */ -/*! \class ExpressionVisitorResult - \internal */ -/*! \class FalseFN - \internal */ -/*! \class FloatComparatorLocator - \internal */ -/*! \class FloatMathematicianLocator - \internal */ -/*! \class FloatType - \internal */ -/*! \class FloorFN - \internal */ -/*! \class FunctionArgument - \internal */ -/*! \class FunctionAvailableFN - \internal */ -/*! \class FunctionFactoryCollection - \internal */ -/*! \class FunctionSignature - \internal */ -/*! \class GDay - \internal */ -/*! \class GDayComparatorLocator - \internal */ -/*! \class GDayType - \internal */ -/*! \class GMonth - \internal */ -/*! \class GMonthComparatorLocator - \internal */ -/*! \class GMonthDay - \internal */ -/*! \class GMonthDayComparatorLocator - \internal */ -/*! \class GMonthDayType - \internal */ -/*! \class GMonthType - \internal */ -/*! \class GYear - \internal */ -/*! \class GYearComparatorLocator - \internal */ -/*! \class GYearMonth - \internal */ -/*! \class GYearMonthComparatorLocator - \internal */ -/*! \class GYearMonthType - \internal */ -/*! \class GYearType - \internal */ -/*! \class HexBinary - \internal */ -/*! \class HexBinaryComparatorLocator - \internal */ -/*! \class HexBinaryToBase64BinaryCaster - \internal */ -/*! \class HexBinaryType - \internal */ -/*! \class HoursFromAbstractDateTimeFN - \internal */ -/*! \class HoursFromDurationFN - \internal */ -/*! \class IdrefFN - \internal */ -/*! \class ImplicitTimezoneFN - \internal */ -/*! \class InScopePrefixesFN - \internal */ -/*! \class IndexOfFN - \internal */ -/*! \class InsertBeforeFN - \internal */ -/*! \class Integer - \internal */ -/*! \class IntegerComparator - \internal */ -/*! \class IntegerComparatorLocator - \internal */ -/*! \class IntegerMathematician - \internal */ -/*! \class IntegerMathematicianLocator - \internal */ -/*! \class DerivedIntegerType - \internal */ -/*! \class IriToURIFN - \internal */ -/*! \class ItemMappingIterator - \internal */ -/*! \class ItemVerifier - \internal */ -/*! \class LangFN - \internal */ -/*! \class LastFN - \internal */ -/*! \class LocalNameFN - \internal */ -/*! \class LocalNameFromQNameFN - \internal */ -/*! \class LowerCaseFN - \internal */ -/*! \class MinutesFromAbstractDateTimeFN - \internal */ -/*! \class MinutesFromDurationFN - \internal */ -/*! \class MonthFromAbstractDateTimeFN - \internal */ -/*! \class MonthsFromDurationFN - \internal */ -/*! \class NOTATIONType - \internal */ -/*! \class NameFN - \internal */ -/*! \class NamePool - \internal */ -/*! \class DelegatingNamespaceResolver - \internal */ -/*! \class GenericNamespaceResolver - \internal */ -/*! \class NodeNamespaceResolver - \internal */ -/*! \class NamespaceURIFN - \internal */ -/*! \class NamespaceURIForPrefixFN - \internal */ -/*! \class NamespaceURIFromQNameFN - \internal */ -/*! \class NilledFN - \internal */ -/*! \class NodeNameFN - \internal */ -/*! \class NormalizeSpaceFN - \internal */ -/*! \class NormalizeUnicodeFN - \internal */ -/*! \class NotFN - \internal */ -/*! \class NumberFN - \internal */ -/*! \class NumericToAbstractFloatCaster - \internal */ -/*! \class NumericToBooleanCaster - \internal */ -/*! \class NumericToDecimalCaster - \internal */ -/*! \class NumericToDerivedIntegerCaster - \internal */ -/*! \class OperandSwitcherMathematician - \internal */ -/*! \class ParserContext - \internal */ -/*! \class MatchesFN - \internal */ -/*! \class ReplaceFN - \internal */ -/*! \class TokenizeFN - \internal */ -/*! \class PositionFN - \internal */ -/*! \class PrefixFromQNameFN - \internal */ -/*! \class AccelTree - \internal */ -/*! \class QNameComparator - \internal */ -/*! \class QNameComparatorLocator - \internal */ -/*! \class QNameFN - \internal */ -/*! \class QNameType - \internal */ -/*! \class QNameValue - \internal */ -/*! \class RemoveFN - \internal */ -/*! \class ResolveQNameFN - \internal */ -/*! \class ResolveURIFN - \internal */ -/*! \class ResourceLoader - \internal */ -/*! \class AccelTreeResourceLoader - \internal */ -/*! \class ReverseFN - \internal */ -/*! \class RootFN - \internal */ -/*! \class RoundFN - \internal */ -/*! \class RoundHalfToEvenFN - \internal */ -/*! \class SchemaTime - \internal */ -/*! \class SchemaTimeComparatorLocator - \internal */ -/*! \class SchemaTimeMathematicianLocator - \internal */ -/*! \class SchemaTimeType - \internal */ -/*! \class SecondsFromAbstractDateTimeFN - \internal */ -/*! \class SecondsFromDurationFN - \internal */ -/*! \class SelfToSelfCaster - \internal */ -/*! \class SequenceMappingIterator - \internal */ -/*! \class SingletonIterator - \internal */ -/*! \class SortTuple - \internal */ -/*! \class StartsWithFN - \internal */ -/*! \class StaticBaseURIFN - \internal */ -/*! \class StaticContext - \internal */ -/*! \class DelegatingStaticContext - \internal */ -/*! \class StaticFocusContext - \internal */ -/*! \class StaticNamespaceContext - \internal */ -/*! \class GenericStaticContext - \internal */ -/*! \class StringComparator - \internal */ -/*! \class StringComparatorLocator - \internal */ -/*! \class StringFN - \internal */ -/*! \class StringJoinFN - \internal */ -/*! \class StringLengthFN - \internal */ -/*! \class StringToAbstractFloatCaster - \internal */ -/*! \class StringToBase64BinaryCaster - \internal */ -/*! \class StringToBooleanCaster - \internal */ -/*! \class StringToCodepointsFN - \internal */ -/*! \class StringToDateCaster - \internal */ -/*! \class StringToDateTimeCaster - \internal */ -/*! \class StringToDayTimeDurationCaster - \internal */ -/*! \class StringToDecimalCaster - \internal */ -/*! \class StringToDerivedIntegerCaster - \internal */ -/*! \class StringToDurationCaster - \internal */ -/*! \class StringToGDayCaster - \internal */ -/*! \class StringToGMonthCaster - \internal */ -/*! \class StringToGMonthDayCaster - \internal */ -/*! \class StringToGYearCaster - \internal */ -/*! \class StringToGYearMonthCaster - \internal */ -/*! \class StringToHexBinaryCaster - \internal */ -/*! \class StringToIntegerCaster - \internal */ -/*! \class StringToTimeCaster - \internal */ -/*! \class StringToYearMonthDurationCaster - \internal */ -/*! \class StringType - \internal */ -/*! \class DerivedStringType - \internal */ -/*! \class SubsequenceFN - \internal */ -/*! \class SubstringAfterFN - \internal */ -/*! \class SubstringBeforeFN - \internal */ -/*! \class SubstringFN - \internal */ -/*! \class SumFN - \internal */ -/*! \class SystemPropertyFN - \internal */ -/*! \class TimezoneFromAbstractDateTimeFN - \internal */ -/*! \class ToAnyURICaster - \internal */ -/*! \class ToAnyURICasterLocator - \internal */ -/*! \class ToBase64BinaryCasterLocator - \internal */ -/*! \class ToBooleanCasterLocator - \internal */ -/*! \class ToDateCasterLocator - \internal */ -/*! \class ToDateTimeCasterLocator - \internal */ -/*! \class ToDayTimeDurationCasterLocator - \internal */ -/*! \class ToDecimalCasterLocator - \internal */ -/*! \class ToDoubleCasterLocator - \internal */ -/*! \class ToDurationCasterLocator - \internal */ -/*! \class ToFloatCasterLocator - \internal */ -/*! \class ToGDayCasterLocator - \internal */ -/*! \class ToGMonthCasterLocator - \internal */ -/*! \class ToGMonthDayCasterLocator - \internal */ -/*! \class ToGYearCasterLocator - \internal */ -/*! \class ToGYearMonthCasterLocator - \internal */ -/*! \class ToHexBinaryCasterLocator - \internal */ -/*! \class ToIntegerCasterLocator - \internal */ -/*! \class ToDerivedIntegerCasterLocator - \internal */ -/*! \class ToQNameCasterLocator - \internal */ -/*! \class ToSchemaTimeCasterLocator - \internal */ -/*! \class ToStringCaster - \internal */ -/*! \class ToStringCasterLocator - \internal */ -/*! \class ToDerivedStringCasterLocator - \internal */ -/*! \class ToUntypedAtomicCaster - \internal */ -/*! \class ToUntypedAtomicCasterLocator - \internal */ -/*! \class ToYearMonthDurationCasterLocator - \internal */ -/*! \class Tokenizer - \internal */ -/*! \class XQueryTokenizer - \internal */ -/*! \class TraceFN - \internal */ -/*! \class TranslateFN - \internal */ -/*! \class TrueFN - \internal */ -/*! \class UntypedAtomic - \internal */ -/*! \class UntypedAtomicConverter - \internal */ -/*! \class ArgumentConverter - \internal */ -/*! \class UntypedAtomicType - \internal */ -/*! \class UpperCaseFN - \internal */ -/*! \class ValidationError - \internal */ -/*! \class VariableDeclaration - \internal */ -/*! \class VariableLoader - \internal */ -/*! \class YearFromAbstractDateTimeFN - \internal */ -/*! \class YearMonthDuration - \internal */ -/*! \class YearMonthDurationComparatorLocator - \internal */ -/*! \class YearMonthDurationMathematicianLocator - \internal */ -/*! \class YearMonthDurationType - \internal */ -/*! \class YearsFromDurationFN - \internal - */ -/*! \class DocumentContentValidator - \internal */ -/*! \class AtomicTypeVisitor - \internal */ -/*! \class AtomicCasterLocator - \internal */ -/*! \class AtomicTypeVisitorResult - \internal */ -/*! \class Expression - \internal */ -/*! \class EmptyContainer - \internal */ -/*! \class AxisStep - \internal */ -/*! \class ContextItem - \internal */ -/*! \class EmptySequence - \internal */ -/*! \class ExternalVariableReference - \internal */ -/*! \class Literal - \internal */ -/*! \class LiteralSequence - \internal */ -/*! \class NamespaceConstructor - \internal */ -/*! \class ParentNodeAxis - \internal */ -/*! \class VariableReference - \internal */ -/*! \class ArgumentReference - \internal */ -/*! \class ExpressionVariableReference - \internal */ -/*! \class PositionalVariableReference - \internal */ -/*! \class RangeVariableReference - \internal */ -/*! \class PairContainer - \internal */ -/*! \class AndExpression - \internal */ -/*! \class OrExpression - \internal */ -/*! \class ArithmeticExpression - \internal */ -/*! \class UnaryExpression - \internal */ -/*! \class AttributeConstructor - \internal */ -/*! \class CombineNodes - \internal */ -/*! \class ElementConstructor - \internal */ -/*! \class ForClause - \internal */ -/*! \class GeneralComparison - \internal */ -/*! \class GenericPredicate - \internal */ -/*! \class TruthPredicate - \internal */ -/*! \class LetClause - \internal */ -/*! \class NodeComparison - \internal */ -/*! \class Path - \internal */ -/*! \class ProcessingInstructionConstructor - \internal */ -/*! \class QuantifiedExpression - \internal */ -/*! \class RangeExpression - \internal */ -/*! \class ValueComparison - \internal */ -/*! \class SingleContainer - \internal */ -/*! \class AttributeNameValidator - \internal */ -/*! \class CastAs - \internal */ -/*! \class CastableAs - \internal */ -/*! \class CollationChecker - \internal */ -/*! \class CommentConstructor - \internal */ -/*! \class CopyOf - \internal */ -/*! \class DocumentConstructor - \internal */ -/*! \class DynamicContextStore - \internal */ -/*! \class FirstItemPredicate - \internal */ -/*! \class InstanceOf - \internal */ -/*! \class NCNameConstructor - \internal */ -/*! \class NodeSortExpression - \internal */ -/*! \class OrderBy - \internal */ -/*! \class QNameConstructor - \internal */ -/*! \class SimpleContentConstructor - \internal */ -/*! \class TextNodeConstructor - \internal */ -/*! \class TreatAs - \internal */ -/*! \class TripleContainer - \internal */ -/*! \class IfThenClause - \internal */ -/*! \class UnlimitedContainer - \internal */ -/*! \class ExpressionSequence - \internal */ -/*! \class ReturnOrderBy - \internal */ -/*! \class UserFunctionCallsite - \internal */ -/*! \class ExpressionCreator - \internal */ -/*! \class ByIDCreator - \internal */ -/*! \class ExpressionFactory - \internal */ -/*! \class ExpressionIdentifier - \internal */ -/*! \class BooleanIdentifier - \internal */ -/*! \class ByIDIdentifier - \internal */ -/*! \class BySequenceTypeIdentifier - \internal */ -/*! \class ComparisonIdentifier - \internal */ -/*! \class IntegerIdentifier - \internal */ -/*! \class ExternalVariableLoader - \internal */ -/*! \class ItemType - \internal */ -/*! \class AnyItemType - \internal */ -/*! \class AnyNodeType - \internal */ -/*! \class AbstractNodeTest - \internal */ -/*! \class LocalNameTest - \internal */ -/*! \class NamespaceNameTest - \internal */ -/*! \class QNameTest - \internal */ -/*! \class AtomicType - \internal */ -/*! \class BuiltinAtomicType - \internal */ -/*! \class AnyAtomicType - \internal */ -/*! \class AnyURIType - \internal */ -/*! \class NumericType - \internal */ -/*! \class EBVType - \internal */ -/*! \class EmptySequenceType - \internal */ -/*! \class MultiItemType - \internal */ -/*! \class NoneType - \internal */ -/*! \class OptimizationPass - \internal */ -/*! \class ParameterizedAtomicTypeVisitor - \internal */ -/*! \class AtomicComparatorLocator - \internal */ -/*! \class AtomicMathematicianLocator - \internal */ -/*! \class SchemaComponent - \internal */ -/*! \class SchemaType - \internal */ -/*! \class AnyType - \internal */ -/*! \class AnySimpleType - \internal */ -/*! \class Untyped - \internal */ -/*! \class SchemaTypeFactory - \internal */ -/*! \class BasicTypesFactory - \internal */ -/*! \class SequenceType - \internal */ -/*! \class GenericSequenceType - \internal */ -/*! \class UserFunction - \internal -*/ -QT_END_NAMESPACE diff --git a/doc/src/qplugin.qdoc b/doc/src/qplugin.qdoc deleted file mode 100644 index 4fbd198..0000000 --- a/doc/src/qplugin.qdoc +++ /dev/null @@ -1,135 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Macros for Defining Plugins - - \brief The header files defines macros for defining plugins. - - \sa {How to Create Qt Plugins} -*/ - -/*! - \macro Q_DECLARE_INTERFACE(ClassName, Identifier) - \relates - - This macro associates the given \a Identifier (a string literal) - to the interface class called \a ClassName. The \a Identifier must - be unique. For example: - - \snippet examples/tools/plugandpaint/interfaces.h 3 - - This macro is normally used right after the class definition for - \a ClassName, in a header file. See the - \l{tools/plugandpaint}{Plug & Paint} example for details. - - If you want to use Q_DECLARE_INTERFACE with interface classes - declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE - is not inside a namespace though. For example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 - - \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_EXPORT_PLUGIN(ClassName) - \relates - \obsolete - - Use Q_EXPORT_PLUGIN2() instead. This macro is equivalent to - Q_EXPORT_PLUGIN2(\a ClassName, \a ClassName). -*/ - -/*! - \macro Q_EXPORT_PLUGIN2(PluginName, ClassName) - \relates - \since 4.1 - \keyword Q_EXPORT_PLUGIN2 - - This macro exports the plugin class \a ClassName for the plugin specified - by \a PluginName. The value of \a PluginName should correspond to the - \l{qmake Variable Reference#TARGET}{TARGET} specified in the plugin's - project file. - - There should be exactly one occurrence of this macro in the source code - for a Qt plugin, and it should be used where the implementation is written - rather than in a header file. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 - - See the \l{tools/plugandpaint}{Plug & Paint} example for details. - - \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_IMPORT_PLUGIN(PluginName) - \relates - - This macro imports the plugin named \a PluginName, corresponding - to the \l{qmake Variable Reference#TARGET}{TARGET} specified in the - plugin's project file. - - Inserting this macro into your application's source code will allow - you to make use of a static plugin. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 - - Static plugins must also be included by the linker when your - application is built. For Qt's predefined plugins, - you can use the \c QTPLUGIN to add - the required plugins to your build. For example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 - - \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} -*/ - -/*! - \macro Q_EXPORT_STATIC_PLUGIN(ClassName) - \relates - \internal -*/ diff --git a/doc/src/qprintdialog.qdoc b/doc/src/qprintdialog.qdoc deleted file mode 100644 index 8011f62..0000000 --- a/doc/src/qprintdialog.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#ifdef QT3_SUPPORT -/*! - \fn QPrinter *QPrintDialog::printer() const - - Returns a pointer to the printer this dialog configures, or 0 if - this dialog does not operate on any printer. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) - - Sets this dialog to configure printer \a printer, or no printer if \a printer - is null. If \a pickupSettings is true, the dialog reads most of - its settings from \a printer. If \a pickupSettings is false (the - default) the dialog keeps its old settings. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::addButton(QPushButton *button) - - Adds the \a button to the layout of the print dialog. The added - buttons are arranged from the left to the right below the - last groupbox of the printdialog. - - This function is available for Unix platforms only. -*/ -#endif diff --git a/doc/src/qprinterinfo.qdoc b/doc/src/qprinterinfo.qdoc deleted file mode 100644 index a4ffeb2..0000000 --- a/doc/src/qprinterinfo.qdoc +++ /dev/null @@ -1,137 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPrinterInfo - - \brief The QPrinterInfo class gives access to information about - existing printers. - - Use the static functions to generate a list of QPrinterInfo - objects. Each QPrinterInfo object in the list represents a single - printer and can be queried for name, supported paper sizes, and - whether or not it is the default printer. - - \since 4.4 -*/ - -/*! - \fn QList QPrinterInfo::availablePrinters() - - Returns a list of available printers on the system. -*/ - -/*! - \fn QPrinterInfo QPrinterInfo::defaultPrinter() - - Returns the default printer on the system. - - The return value should be checked using isNull() before being - used, in case there is no default printer. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo() - - Constructs an empty QPrinterInfo object. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinterInfo& src) - - Constructs a copy of \a src. -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinter& printer) - - Constructs a QPrinterInfo object from \a printer. -*/ - -/*! - \fn QPrinterInfo::~QPrinterInfo() - - Destroys the QPrinterInfo object. References to the values in the - object become invalid. -*/ - -/*! - \fn QPrinterInfo& QPrinterInfo::operator=(const QPrinterInfo& src) - - Sets the QPrinterInfo object to be equal to \a src. -*/ - -/*! - \fn QString QPrinterInfo::printerName() const - - Returns the name of the printer. - - \sa QPrinter::setPrinterName() -*/ - -/*! - \fn bool QPrinterInfo::isNull() const - - Returns whether this QPrinterInfo object holds a printer definition. - - An empty QPrinterInfo object could result for example from calling - defaultPrinter() when there are no printers on the system. -*/ - -/*! - \fn bool QPrinterInfo::isDefault() const - - Returns whether this printer is the default printer. -*/ - -/*! - \fn QList< QPrinter::PaperSize> QPrinterInfo::supportedPaperSizes() const - \since 4.4 - - Returns a list of supported paper sizes by the printer. - - Not all printer drivers support this query, so the list may be empty. - On Mac OS X 10.3, this function always returns an empty list. -*/ diff --git a/doc/src/qset.qdoc b/doc/src/qset.qdoc deleted file mode 100644 index 0db3775..0000000 --- a/doc/src/qset.qdoc +++ /dev/null @@ -1,953 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSet - \brief The QSet class is a template class that provides a hash-table-based set. - - \ingroup tools - \ingroup shared - \reentrant - \mainclass - - QSet is one of Qt's generic \l{container classes}. It stores - values in an unspecified order and provides very fast lookup of - the values. Internally, QSet is implemented as a QHash. - - Here's an example QSet with QString values: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 - - To insert a value into the set, use insert(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 - - Another way to insert items into the set is to use operator<<(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 - - To test whether an item belongs to the set or not, use contains(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 - - If you want to navigate through all the values stored in a QSet, - you can use an iterator. QSet supports both \l{Java-style - iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style - iterators} (QSet::iterator and QSet::const_iterator). Here's how - to iterate over a QSet using a Java-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 - - Here's the same code, but using an STL-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 - - QSet is unordered, so an iterator's sequence cannot be assumed to - be predictable. If ordering by key is required, use a QMap. - - To navigate through a QSet, you can also use \l{foreach}: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 - - Items can be removed from the set using remove(). There is also a - clear() function that removes all items. - - QSet's value data type must be an \l{assignable data type}. You - cannot, for example, store a QWidget as a value; instead, store a - QWidget *. In addition, the type must provide \c operator==(), and - there must also be a global qHash() function that returns a hash - value for an argument of the key's type. See the QHash - documentation for a list of types supported by qHash(). - - Internally, QSet uses a hash table to perform lookups. The hash - table automatically grows and shrinks to provide fast lookups - without wasting memory. You can still control the size of the hash - table by calling reserve(), if you already know approximately how - many elements the QSet will contain, but this isn't necessary to - obtain good performance. You can also call capacity() to retrieve - the hash table's size. - - \sa QSetIterator, QMutableSetIterator, QHash, QMap -*/ - -/*! - \fn QSet::QSet() - - Constructs an empty set. - - \sa clear() -*/ - -/*! - \fn QSet::QSet(const QSet &other) - - Constructs a copy of \a other. - - This operation occurs in \l{constant time}, because QSet is - \l{implicitly shared}. This makes returning a QSet from a - function very fast. If a shared instance is modified, it will be - copied (copy-on-write), and this takes \l{linear time}. - - \sa operator=() -*/ - -/*! - \fn QSet &QSet::operator=(const QSet &other) - - Assigns the \a other set to this set and returns a reference to - this set. -*/ - -/*! - \fn bool QSet::operator==(const QSet &other) const - - Returns true if the \a other set is equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator!=() -*/ - -/*! - \fn bool QSet::operator!=(const QSet &other) const - - Returns true if the \a other set is not equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator==() -*/ - -/*! - \fn int QSet::size() const - - Returns the number of items in the set. - - \sa isEmpty(), count() -*/ - -/*! - \fn bool QSet::isEmpty() const - - Returns true if the set contains no elements; otherwise returns - false. - - \sa size() -*/ - -/*! - \fn int QSet::capacity() const - - Returns the number of buckets in the set's internal hash - table. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever need - to call this function. If you want to know how many items are in - the set, call size(). - - \sa reserve(), squeeze() -*/ - -/*! \fn void QSet::reserve(int size) - - Ensures that the set's internal hash table consists of at - least \a size buckets. - - This function is useful for code that needs to build a huge set - and wants to avoid repeated reallocation. For example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 - - Ideally, \a size should be slightly more than the maximum number - of elements expected in the set. \a size doesn't have to be prime, - because QSet will use a prime number internally anyway. If \a size - is an underestimate, the worst that will happen is that the QSet - will be a bit slower. - - In general, you will rarely ever need to call this function. - QSet's internal hash table automatically shrinks or grows to - provide good performance without wasting too much memory. - - \sa squeeze(), capacity() -*/ - -/*! - \fn void QSet::squeeze() - - Reduces the size of the set's internal hash table to save - memory. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever - need to call this function. - - \sa reserve(), capacity() -*/ - -/*! - \fn void QSet::detach() - - \internal - - Detaches this set from any other sets with which it may share - data. - - \sa isDetached() -*/ - -/*! \fn bool QSet::isDetached() const - - \internal - - Returns true if the set's internal data isn't shared with any - other set object; otherwise returns false. - - \sa detach() -*/ - -/*! - \fn void QSet::setSharable(bool sharable) - \internal -*/ - -/*! - \fn void QSet::clear() - - Removes all elements from the set. - - \sa remove() -*/ - -/*! - \fn bool QSet::remove(const T &value) - - Removes any occurrence of item \a value from the set. Returns - true if an item was actually removed; otherwise returns false. - - \sa contains(), insert() -*/ - -/*! - \fn QSet::iterator QSet::erase(iterator pos) - \since 4.2 - - Removes the item at the iterator position \a pos from the set, and - returns an iterator positioned at the next item in the set. - - Unlike remove(), this function never causes QSet to rehash its - internal data structure. This means that it can safely be called - while iterating, and won't affect the order of items in the set. - - \sa remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::find(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa constFind(), contains() -*/ - -/*! \fn QSet::iterator QSet::find(const T &value) - \since 4.2 - \overload - - Returns a non-const iterator positioned at the item \a value in - the set. If the set contains no item \a value, the function - returns end(). -*/ - -/*! \fn QSet::const_iterator QSet::constFind(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa find(), contains() -*/ - -/*! - \fn bool QSet::contains(const T &value) const - - Returns true if the set contains item \a value; otherwise returns - false. - - \sa insert(), remove(), find() -*/ - -/*! - \fn bool QSet::contains(const QSet &other) const - \since 4.6 - - Returns true if the set contains all items from the \a other set; - otherwise returns false. - - \sa insert(), remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::begin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa constBegin(), end() -*/ - -/*! \fn QSet::iterator QSet::begin() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} positioned at the first - item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constBegin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa begin(), constEnd() -*/ - -/*! \fn QSet::const_iterator QSet::end() const - - Returns a const \l{STL-style iterator} positioned at the imaginary - item after the last item in the set. - - \sa constEnd(), begin() -*/ - -/*! \fn QSet::iterator QSet::end() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} pointing to the - imaginary item after the last item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constEnd() const - - Returns a const \l{STL-style iterator} pointing to the imaginary - item after the last item in the set. - - \sa constBegin(), end() -*/ - -/*! - \typedef QSet::Iterator - \since 4.2 - - Qt-style synonym for QSet::iterator. -*/ - -/*! - \typedef QSet::ConstIterator - - Qt-style synonym for QSet::const_iterator. -*/ - -/*! - \typedef QSet::const_pointer - - Typedef for const T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::const_reference - - Typedef for const T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::difference_type - - Typedef for const ptrdiff_t. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::key_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::pointer - - Typedef for T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::reference - - Typedef for T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::size_type - - Typedef for int. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::value_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \fn QSet::const_iterator QSet::insert(const T &value) - - Inserts item \a value into the set, if \a value isn't already - in the set, and returns an iterator pointing at the inserted - item. - - \sa operator<<(), remove(), contains() -*/ - -/*! - \fn QSet &QSet::unite(const QSet &other) - - Each item in the \a other set that isn't already in this set is - inserted into this set. A reference to this set is returned. - - \sa operator|=(), intersect(), subtract() -*/ - -/*! - \fn QSet &QSet::intersect(const QSet &other) - - Removes all items from this set that are not contained in the - \a other set. A reference to this set is returned. - - \sa operator&=(), unite(), subtract() -*/ - -/*! - \fn QSet &QSet::subtract(const QSet &other) - - Removes all items from this set that are contained in the - \a other set. Returns a reference to this set. - - \sa operator-=(), unite(), intersect() -*/ - -/*! - \fn bool QSet::empty() const - - Returns true if the set is empty. This function is provided - for STL compatibility. It is equivalent to isEmpty(). -*/ - -/*! - \fn bool QSet::count() const - - Same as size(). -*/ - -/*! - \fn QSet &QSet::operator<<(const T &value) - \fn QSet &QSet::operator+=(const T &value) - \fn QSet &QSet::operator|=(const T &value) - - Inserts a new item \a value and returns a reference to the set. - If \a value already exists in the set, the set is left unchanged. - - \sa insert() -*/ - -/*! - \fn QSet &QSet::operator-=(const T &value) - - Removes the occurrence of item \a value from the set, if - it is found, and returns a reference to the set. If the - \a value is not contained the set, nothing is removed. - - \sa remove() -*/ - -/*! - \fn QSet &QSet::operator|=(const QSet &other) - \fn QSet &QSet::operator+=(const QSet &other) - - Same as unite(\a other). - - \sa operator|(), operator&=(), operator-=() -*/ - -/*! - \fn QSet &QSet::operator&=(const QSet &other) - - Same as intersect(\a other). - - \sa operator&(), operator|=(), operator-=() -*/ - -/*! - \fn QSet &QSet::operator&=(const T &value) - - \overload - - Same as intersect(\e{other}), if we consider \e{other} to be a set - that contains the singleton \a value. -*/ - - -/*! - \fn QSet &QSet::operator-=(const QSet &other) - - Same as subtract(\a{other}). - - \sa operator-(), operator|=(), operator&=() -*/ - -/*! - \fn QSet QSet::operator|(const QSet &other) const - \fn QSet QSet::operator+(const QSet &other) const - - Returns a new QSet that is the union of this set and the - \a other set. - - \sa unite(), operator|=(), operator&(), operator-() -*/ - -/*! - \fn QSet QSet::operator&(const QSet &other) const - - Returns a new QSet that is the intersection of this set and the - \a other set. - - \sa intersect(), operator&=(), operator|(), operator-() -*/ - -/*! - \fn QSet QSet::operator-(const QSet &other) const - - Returns a new QSet that is the set difference of this set and - the \a other set, i.e., this set - \a other set. - - \sa subtract(), operator-=(), operator|(), operator&() -*/ - -/*! - \fn QSet QSet::operator-(const QSet &other) - \fn QSet QSet::operator|(const QSet &other) - \fn QSet QSet::operator+(const QSet &other) - \fn QSet QSet::operator&(const QSet &other) - \internal - - These will go away in Qt 5. -*/ - -/*! - \class QSet::iterator - \since 4.2 - \brief The QSet::iterator class provides an STL-style non-const iterator for QSet. - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet::iterator allows you to iterate over a QSet and to remove - items (using QSet::erase()) while you iterate. (QSet doesn't let - you \e modify a value through an iterator, because that - would potentially require moving the value in the internal hash - table used by QSet.) If you want to iterate over a const QSet, - you should use QSet::const_iterator. It is generally good - practice to use QSet::const_iterator on a non-const QSet as well, - unless you need to change the QSet through the iterator. Const - iterators are slightly faster, and can improve code readability. - - QSet\::iterator allows you to iterate over a QSet\ and - modify it as you go (using QSet::erase()). However, - - The default QSet::iterator constructor creates an uninitialized - iterator. You must initialize it using a function like - QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 - - Here's a loop that removes certain items (all those that start - with 'J') from a set while iterating: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::const_iterator, QMutableSetIterator -*/ - -/*! - \class QSet::const_iterator - \brief The QSet::const_iterator class provides an STL-style const iterator for QSet. - \since 4.2 - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet\::const_iterator allows you to iterate over a QSet. - If you want to modify the QSet as you iterate over it, you must - use QSet::iterator instead. It is generally good practice to use - QSet::const_iterator on a non-const QSet as well, unless you need - to change the QSet through the iterator. Const iterators are - slightly faster, and can improve code readability. - - The default QSet::const_iterator constructor creates an - uninitialized iterator. You must initialize it using a function - like QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::iterator, QSetIterator -*/ - -/*! - \fn QSet::iterator::iterator() - \fn QSet::const_iterator::const_iterator() - - Constructs an uninitialized iterator. - - Functions like operator*() and operator++() should not be called - on an uninitialized iterator. Use operator=() to assign a value - to it before using it. - - \sa QSet::begin(), QSet::end() -*/ - -/*! - \fn QSet::iterator::iterator(typename Hash::iterator i) - \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i) - - \internal -*/ - -/*! - \typedef QSet::iterator::iterator_category - \typedef QSet::const_iterator::iterator_category - - Synonyms for \e {std::bidirectional_iterator_tag} indicating - these iterators are bidirectional iterators. - */ - -/*! - \typedef QSet::iterator::difference_type - \typedef QSet::const_iterator::difference_type - - \internal -*/ - -/*! - \typedef QSet::iterator::value_type - \typedef QSet::const_iterator::value_type - - \internal -*/ - -/*! - \typedef QSet::iterator::pointer - \typedef QSet::const_iterator::pointer - - \internal -*/ - -/*! - \typedef QSet::iterator::reference - \typedef QSet::const_iterator::reference - - \internal -*/ - -/*! - \fn QSet::iterator::iterator(const iterator &other) - \fn QSet::const_iterator::const_iterator(const const_iterator &other) - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::const_iterator::const_iterator(const iterator &other) - \since 4.2 - \overload - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator=(const iterator &other) - \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other) - - Assigns \a other to this iterator. -*/ - -/*! - \fn const T &QSet::iterator::operator*() const - \fn const T &QSet::const_iterator::operator*() const - - Returns a reference to the current item. - - \sa operator->() -*/ - -/*! - \fn const T *QSet::iterator::operator->() const - \fn const T *QSet::const_iterator::operator->() const - - Returns a pointer to the current item. - - \sa operator*() -*/ - -/*! - \fn bool QSet::iterator::operator==(const iterator &other) const - \fn bool QSet::const_iterator::operator==(const const_iterator &other) const - - Returns true if \a other points to the same item as this - iterator; otherwise returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSet::iterator::operator==(const const_iterator &other) const - \fn bool QSet::iterator::operator!=(const const_iterator &other) const - - \overload -*/ - -/*! - \fn bool QSet::iterator::operator!=(const iterator &other) const - \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const - - Returns true if \a other points to a different item than this - iterator; otherwise returns false. - - \sa operator==() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator++() - \fn QSet::const_iterator &QSet::const_iterator::operator++() - - The prefix ++ operator (\c{++it}) advances the iterator to the - next item in the set and returns an iterator to the new current - item. - - Calling this function on QSet::constEnd() leads to - undefined results. - - \sa operator--() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator++(int) - \fn QSet::const_iterator QSet::const_iterator::operator++(int) - - \overload - - The postfix ++ operator (\c{it++}) advances the iterator to the - next item in the set and returns an iterator to the previously - current item. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator--() - \fn QSet::const_iterator &QSet::const_iterator::operator--() - - The prefix -- operator (\c{--it}) makes the preceding item - current and returns an iterator to the new current item. - - Calling this function on QSet::begin() leads to undefined - results. - - \sa operator++() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator--(int) - \fn QSet::const_iterator QSet::const_iterator::operator--(int) - - \overload - - The postfix -- operator (\c{it--}) makes the preceding item - current and returns an iterator to the previously current item. -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator+(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const - - Returns an iterator to the item at \a j positions forward from - this iterator. (If \a j is negative, the iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator-(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const - - Returns an iterator to the item at \a j positions backward from - this iterator. (If \a j is negative, the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator+=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j) - - Advances the iterator by \a j items. (If \a j is negative, the - iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-=(), operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator-=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j) - - Makes the iterator go back by \a j items. (If \a j is negative, - the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+=(), operator-() -*/ - -/*! \fn QList QSet::toList() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 - - \sa fromList(), QList::fromSet(), qSort() -*/ - -/*! \fn QList QSet::values() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - This is the same as toList(). - - \sa fromList(), QList::fromSet(), qSort() -*/ - - -/*! \fn QSet QSet::fromList(const QList &list) - - Returns a new QSet object containing the data contained in \a - list. Since QSet doesn't allow duplicates, the resulting QSet - might be smaller than the \a list, because QList can contain - duplicates. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 - - \sa toList(), QList::toSet() -*/ - -/*! - \fn QDataStream &operator<<(QDataStream &out, const QSet &set) - \relates QSet - - Writes the \a set to stream \a out. - - This function requires the value type to implement \c operator<<(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ - -/*! - \fn QDataStream &operator>>(QDataStream &in, QSet &set) - \relates QSet - - Reads a set from stream \a in into \a set. - - This function requires the value type to implement \c operator>>(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ diff --git a/doc/src/qsignalspy.qdoc b/doc/src/qsignalspy.qdoc deleted file mode 100644 index 4ee7590..0000000 --- a/doc/src/qsignalspy.qdoc +++ /dev/null @@ -1,98 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSignalSpy - \inmodule QtTest - - \brief The QSignalSpy class enables introspection of signal emission. - - QSignalSpy can connect to any signal of any object and records its emission. - QSignalSpy itself is a list of QVariant lists. Each emission of the signal - will append one item to the list, containing the arguments of the signal. - - The following example records all signal emissions for the \c clicked() signal - of a QCheckBox: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 - - \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a - list of QVariant objects. The \c clicked() signal has a single bool argument, - which is stored as the first entry in the list of arguments. - - The example below catches a signal from a custom object: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 - - \bold {Note:} Non-standard data types need to be registered, using - the qRegisterMetaType() function, before you can create a - QSignalSpy. For example: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 - - To retrieve the \c QModelIndex, you can use qvariant_cast: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 - */ - -/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) - - Constructs a new QSignalSpy that listens for emissions of the \a signal - from the QObject \a object. Neither \a signal nor \a object can be null. - - Example: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 -*/ - -/*! \fn QSignalSpy::isValid() const - - Returns true if the signal spy listens to a valid signal, otherwise false. -*/ - -/*! \fn QSignalSpy::signal() const - - Returns the normalized signal the spy is currently listening to. -*/ - -/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a) - \internal -*/ - diff --git a/doc/src/qsizepolicy.qdoc b/doc/src/qsizepolicy.qdoc deleted file mode 100644 index c74beb8..0000000 --- a/doc/src/qsizepolicy.qdoc +++ /dev/null @@ -1,522 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSizePolicy - \brief The QSizePolicy class is a layout attribute describing horizontal - and vertical resizing policy. - - \ingroup appearance - \ingroup geomanagement - - The size policy of a widget is an expression of its willingness to - be resized in various ways, and affects how the widget is treated - by the \l{Layout Management}{layout engine}. Each widget returns a - QSizePolicy that describes the horizontal and vertical resizing - policy it prefers when being laid out. You can change this for - a specific widget by changing its QWidget::sizePolicy property. - - QSizePolicy contains two independent QSizePolicy::Policy values - and two stretch factors; one describes the widgets's horizontal - size policy, and the other describes its vertical size policy. It - also contains a flag to indicate whether the height and width of - its preferred size are related. - - The horizontal and vertical policies can be set in the - constructor, and altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. The stretch factors can be set - using the setHorizontalStretch() and setVerticalStretch() - functions. The flag indicating whether the widget's - \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a - menu bar or a word-wrapping label) can be set using the - setHeightForWidth() function. - - The current size policies and stretch factors be retrieved using - the horizontalPolicy(), verticalPolicy(), horizontalStretch() and - verticalStretch() functions. Alternatively, use the transpose() - function to swap the horizontal and vertical policies and - stretches. The hasHeightForWidth() function returns the current - status of the flag indicating the size hint dependencies. - - Use the expandingDirections() function to determine whether the - associated widget can make use of more space than its - \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as - find out in which directions it can expand. - - Finally, the QSizePolicy class provides operators comparing this - size policy to a given policy, as well as a QVariant operator - storing this QSizePolicy as a QVariant object. - - \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy, - QLayoutItem::sizeHint() -*/ - -/*! - \enum QSizePolicy::PolicyFlag - - These flags are combined together to form the various \l{Policy} - values: - - \value GrowFlag The widget can grow beyond its size hint if necessary. - \value ExpandFlag The widget should get as much space as possible. - \value ShrinkFlag The widget can shrink below its size hint if necessary. - \value IgnoreFlag The widget's size hint is ignored. The widget will get - as much space as possible. - - \sa Policy -*/ - -/*! - \enum QSizePolicy::Policy - - This enum describes the various per-dimension sizing types used - when constructing a QSizePolicy. - - \value Fixed The QWidget::sizeHint() is the only acceptable - alternative, so the widget can never grow or shrink (e.g. the - vertical direction of a push button). - - \value Minimum The sizeHint() is minimal, and sufficient. The - widget can be expanded, but there is no advantage to it being - larger (e.g. the horizontal direction of a push button). - It cannot be smaller than the size provided by sizeHint(). - - \value Maximum The sizeHint() is a maximum. The widget can be - shrunk any amount without detriment if other widgets need the - space (e.g. a separator line). - It cannot be larger than the size provided by sizeHint(). - - \value Preferred The sizeHint() is best, but the widget can be - shrunk and still be useful. The widget can be expanded, but there - is no advantage to it being larger than sizeHint() (the default - QWidget policy). - - \value Expanding The sizeHint() is a sensible size, but the - widget can be shrunk and still be useful. The widget can make use - of extra space, so it should get as much space as possible (e.g. - the horizontal direction of a horizontal slider). - - \value MinimumExpanding The sizeHint() is minimal, and sufficient. - The widget can make use of extra space, so it should get as much - space as possible (e.g. the horizontal direction of a horizontal - slider). - - \value Ignored The sizeHint() is ignored. The widget will get as - much space as possible. - - \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy() -*/ - -/*! - \fn QSizePolicy::QSizePolicy() - - Constructs a QSizePolicy object with \l Fixed as its horizontal - and vertical policies. - - The policies can be altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. Use the setHeightForWidth() - function if the preferred height of the widget is dependent on the - width of the widget (for example, a QLabel with line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical) - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and DefaultType as the control type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type) - \since 4.3 - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and the specified control \a type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch(), controlType() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const - - Returns the horizontal component of the size policy. - - \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const - - Returns the vertical component of the size policy. - - \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch() -*/ - -/*! - \fn void QSizePolicy::setHorizontalPolicy(Policy policy) - - Sets the horizontal component to the given \a policy. - - \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch() -*/ - -/*! - \fn void QSizePolicy::setVerticalPolicy(Policy policy) - - Sets the vertical component to the given \a policy. - - \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch() -*/ - -/*! - \fn Qt::Orientations QSizePolicy::expandingDirections() const - - Returns whether a widget can make use of more space than the - QWidget::sizeHint() function indicates. - - A value of Qt::Horizontal or Qt::Vertical means that the widget - can grow horizontally or vertically (i.e., the horizontal or - vertical policy is \l Expanding or \l MinimumExpanding), whereas - Qt::Horizontal | Qt::Vertical means that it can grow in both - dimensions. - - \sa horizontalPolicy(), verticalPolicy() -*/ - -/*! - \fn ControlType QSizePolicy::controlType() const - \since 4.3 - - Returns the control type associated with the widget for which - this size policy applies. -*/ - -/*! - \fn void QSizePolicy::setControlType(ControlType type) - \since 4.3 - - Sets the control type associated with the widget for which this - size policy applies to \a type. - - The control type specifies the type of the widget for which this - size policy applies. It is used by some styles, notably - QMacStyle, to insert proper spacing between widgets. For example, - the Mac OS X Aqua guidelines specify that push buttons should be - separated by 12 pixels, whereas vertically stacked radio buttons - only require 6 pixels. - - \sa QStyle::layoutSpacing() -*/ - -/*! - \fn void QSizePolicy::setHeightForWidth(bool dependent) - - Sets the flag determining whether the widget's preferred height - depends on its width, to \a dependent. - - \sa hasHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::hasHeightForWidth() const - - Returns true if the widget's preferred height depends on its - width; otherwise returns false. - - \sa setHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::operator==(const QSizePolicy &other) const - - Returns true if this policy is equal to \a other; otherwise - returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const - - Returns true if this policy is different from \a other; otherwise - returns false. - - \sa operator==() -*/ - -/*! - \fn int QSizePolicy::horizontalStretch() const - - Returns the horizontal stretch factor of the size policy. - - \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy() -*/ - -/*! - \fn int QSizePolicy::verticalStretch() const - - Returns the vertical stretch factor of the size policy. - - \sa setVerticalStretch(), horizontalStretch(), verticalPolicy() -*/ - -/*! - \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor) - - Sets the horizontal stretch factor of the size policy to the given \a - stretchFactor. - - \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy() -*/ - -/*! - \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor) - - Sets the vertical stretch factor of the size policy to the given - \a stretchFactor. - - \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy() -*/ - -/*! - \fn void QSizePolicy::transpose() - - Swaps the horizontal and vertical policies and stretches. -*/ - -/*! - \enum QSizePolicy::ControlType - \since 4.3 - - This enum specifies the different types of widgets in terms of - layout interaction: - - \value DefaultType The default type, when none is specified. - \value ButtonBox A QDialogButtonBox instance. - \value CheckBox A QCheckBox instance. - \value ComboBox A QComboBox instance. - \value Frame A QFrame instance. - \value GroupBox A QGroupBox instance. - \value Label A QLabel instance. - \value Line A QFrame instance with QFrame::HLine or QFrame::VLine. - \value LineEdit A QLineEdit instance. - \value PushButton A QPushButton instance. - \value RadioButton A QRadioButton instance. - \value Slider A QAbstractSlider instance. - \value SpinBox A QAbstractSpinBox instance. - \value TabWidget A QTabWidget instance. - \value ToolButton A QToolButton instance. - - \sa setControlType(), controlType() -*/ - -#ifdef QT3_SUPPORT -/*! - \typedef QSizePolicy::SizeType - \compat - - Use the QSizePolicy::Policy enum instead. -*/ - -/*! - \enum QSizePolicy::ExpandData - \compat - - Use the Qt::Orientations enum instead. - - \value NoDirection Use 0 instead. - \value Horizontally Use Qt::Horizontal instead. - \value Vertically Use Qt::Vertical instead. - \value BothDirections Use Qt::Horizontal | Qt::Vertical instead. -*/ - -/*! - \fn bool QSizePolicy::mayShrinkHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayShrinkVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const - - Use expandingDirections() instead. -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent) - - Use the QSizePolicy() constructor and the setHeightForWidth() - function instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch, - uchar verticalStretch, bool dependent) - - Use the QSizePolicy() constructor and call the - setHorizontalStretch(), setVerticalStretch(), and - setHeightForWidth() functions instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, - horizontalStretch, verticalStretch, - dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHorizontalStretch(horizontalStretch); - policy->setVerticalStretch(verticalStretch); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horData() const - - Use horizontalPolicy() instead. -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verData() const - - Use verticalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setHorData(Policy policy) - - Use setHorizontalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setVerData(Policy policy) - - Use setVerticalPolicy() instead. -*/ - -/*! - \fn uint QSizePolicy::horStretch() const - - Use horizontalStretch() instead. -*/ - -/*! - \fn uint QSizePolicy::verStretch() const - - Use verticalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setHorStretch(uchar stretch) - - Use setHorizontalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setVerStretch(uchar stretch) - - Use setVerticalStretch() instead. -*/ -#endif diff --git a/doc/src/qstyles.qdoc b/doc/src/qstyles.qdoc deleted file mode 100644 index ae2d95b..0000000 --- a/doc/src/qstyles.qdoc +++ /dev/null @@ -1,261 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - - -/*! - \class QMacStyle - \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. - - \ingroup appearance - - This class is implemented as a wrapper to the HITheme - APIs, allowing applications to be styled according to the current - theme in use on Mac OS X. This is done by having primitives - in QStyle implemented in terms of what Mac OS X would normally theme. - - \warning This style is only available on Mac OS X because it relies on the - HITheme APIs. - - There are additional issues that should be taken - into consideration to make an application compatible with the - \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html - Apple Human Interface Guidelines \endlink. Some of these issues are outlined - below. - - \list - - \i Layout - The restrictions on window layout are such that some - aspects of layout that are style-dependent cannot be achieved - using QLayout. Changes are being considered (and feedback would be - appreciated) to make layouts QStyle-able. Some of the restrictions - involve horizontal and vertical widget alignment and widget size - (covered below). - - \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt - does not fully implement this behavior so as to maintain cross-platform - compatibility. As a result some widgets sizes may be inappropriate (and - subsequently not rendered correctly by the HITheme APIs).The - QWidget::sizeHint() will return the appropriate size for many - managed widgets (widgets enumerated in \l QStyle::ContentsType). - - \i Effects - QMacStyle uses HITheme for performing most of the drawing, but - also uses emulation in a few cases where HITheme does not provide the - required functionality (for example, tab bars on Panther, the toolbar - separator, etc). We tried to make the emulation as close to the original as - possible. Please report any issues you see in effects or non-standard - widgets. - - \endlist - - There are other issues that need to be considered in the feel of - your application (including the general color scheme to match the - Aqua colors). The Guidelines mentioned above will remain current - with new advances and design suggestions for Mac OS X. - - Note that the functions provided by QMacStyle are - reimplementations of QStyle functions; see QStyle for their - documentation. - - \img qmacstyle.png - \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle -*/ - - -/*! - \enum QMacStyle::WidgetSizePolicy - - \value SizeSmall - \value SizeLarge - \value SizeMini - \value SizeDefault - \omitvalue SizeNone -*/ - -/*! \fn QMacStyle::QMacStyle() - Constructs a QMacStyle object. -*/ - -/*! \fn QMacStyle::~QMacStyle() - Destructs a QMacStyle object. -*/ - -/*! \fn void QMacStyle::polish(QPalette &pal) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QWidget* w) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QWidget* w) - \reimp -*/ - -/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QPalette QMacStyle::standardPalette() const - \reimp -*/ - -/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! - \enum QMacStyle::FocusRectPolicy - - This type is used to signify a widget's focus rectangle policy. - - \value FocusEnabled show a focus rectangle when the widget has focus. - \value FocusDisabled never show a focus rectangle for the widget. - \value FocusDefault show a focus rectangle when the widget has - focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, - QListBox, QListView, editable QTextEdit, or one of their - subclasses. -*/ - -/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) - \obsolete - Sets the focus rectangle policy of \a w. The \a policy can be one of - \l{QMacStyle::FocusRectPolicy}. - - This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the - FocusDefault value does nothing anymore. If you want to set a widget back - to its default value, you must save the old value of the attribute before - you change it. - - \sa focusRectPolicy() QWidget::setAttribute() -*/ - -/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) - \obsolete - Returns the focus rectangle policy for the widget \a w. - - The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. - - In 4.3 and up this function will simply test for the - Qt::WA_MacShowFocusRect attribute and will never return - QMacStyle::FocusDefault. - - \sa setFocusRectPolicy(), QWidget::testAttribute() -*/ - -/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) - - \obsolete - - Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) - \obsolete - - Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const - \reimp -*/ - -/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const - \reimp -*/ - -/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const - \reimp -*/ - -/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const - \reimp -*/ - -/*! \fn bool QMacStyle::event(QEvent *e) - \reimp -*/ - -/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const - \internal -*/ - -/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const - - \internal -*/ - diff --git a/doc/src/qtdesigner.qdoc b/doc/src/qtdesigner.qdoc index d913b32..0959bd9 100644 --- a/doc/src/qtdesigner.qdoc +++ b/doc/src/qtdesigner.qdoc @@ -166,1376 +166,3 @@ \sa {Qt Designer Manual}, {QtUiTools Module} */ - -/*! - \class QDesignerMemberSheetExtension - - \brief The QDesignerMemberSheetExtension class allows you to - manipulate a widget's member functions which is displayed when - configuring connections using Qt Designer's mode for editing - signals and slots. - - \inmodule QtDesigner - - QDesignerMemberSheetExtension is a collection of functions that is - typically used to query a widget's member functions, and to - manipulate the member functions' appearance in \QD's signals and - slots editing mode. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The member sheet (and any other extension), can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default member sheet used in \QD's signals and - slots editing mode with the widget's member functions. But - QDesignerMemberSheetExtension also provides an interface for - creating custom member sheet extensions. - - \warning \QD uses the QDesignerMemberSheetExtension to facilitate - the signal and slot editing mode. Whenever a connection between - two widgets is requested, \QD will query for the widgets' member - sheet extensions. If a widget has an implemented member sheet - extension, this extension will override the default member sheet. - - To create a member sheet extension, your extension class must - inherit from both QObject and QDesignerMemberSheetExtension. Then, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 - - This enables \QD to use qobject_cast() to query for - supported interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a member sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a widget's member sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a member sheet - extension for that widget, is found. This factory will then make - an instance of the extension. If no such factory is found, \QD - will use the default member sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and - QDesignerTaskMenuExtension. \QD's behavior is the same whether the - requested extension is associated with a multi page container, a - member sheet, a property sheet or a task menu. - - The QExtensionFactory class provides a standard extension - factory, and can also be used as an interface for custom - extension factories. You can either create a new - QExtensionFactory and reimplement the - QExtensionFactory::createExtension() function. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a member sheet extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 - - For a complete example using an extension class, see \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() - - Destroys the member sheet extension. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::count() const - - Returns the extension's number of member functions. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const - - Returns the index of the member function specified by the given \a - name. - - \sa memberName() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberName(int index) const - - Returns the name of the member function with the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const - - Returns the name of the member group specified for the function - with the given \a index. - - \sa indexOf(), setMemberGroup() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) - - Sets the member group of the member function with the given \a - index, to \a group. - - \sa indexOf(), memberGroup() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isVisible(int index) const - - Returns true if the member function with the given \a index is - visible in \QD's signal and slot editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the member function with the given \a index - is visible in \QD's signals and slots editing mode; otherwise the - member function is hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const - - Returns true if the member function with the given \a index is a - signal, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isSlot(int index) const - - Returns true if the member function with the given \a index is a - slot, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const - - Returns true if the member function with the given \a index is - inherited from QWidget, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const - - Returns the name of the class in which the member function with - the given \a index is declared. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::signature(int index) const - - Returns the signature of the member function with the given \a - index. - - \sa indexOf() -*/ - -/*! - \fn QList QDesignerMemberSheetExtension::parameterTypes(int index) const - - Returns the parameter types of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterNames() -*/ - -/*! - \fn QList QDesignerMemberSheetExtension::parameterNames(int index) const - - Returns the parameter names of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterTypes() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerLayoutDecorationExtension - \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerLayoutDecorationExtension::InsertMode - - This enum describes the modes that are used to insert items into a layout. - - \value InsertWidgetMode Widgets are inserted into empty cells in a layout. - \value InsertRowMode Whole rows are inserted into a vertical or grid layout. - \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. -*/ - -/*! - \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() - - Destroys the extension. -*/ - -/*! - \fn virtual QList QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const - - Returns the widgets that are managed by the given \a layout. - - \sa insertWidget(), removeWidget() -*/ - -/*! - \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const - - Returns the rectangle covered by the item at the given \a index in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const - - Returns the index of the specified \a widget in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const - - Returns the index of the specified layout \a item. -*/ - -/*! - \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const - - Returns the current insertion mode. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::currentIndex() const - - Returns the current index in the layout. -*/ - -/*! - \fn QPair QDesignerLayoutDecorationExtension::currentCell() const - - Returns a pair containing the row and column of the current cell in the layout. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair &cell) - - Inserts the given \a widget into the specified \a cell in the layout. - - \sa removeWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) - - Removes the specified \a widget from the layout. - - \sa insertWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertRow(int row) - - Inserts a new row into the form at the position specified by \a row. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) - - Inserts a new column into the form at the position specified by \a column. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::simplify() - - Simplifies the layout by removing unnecessary empty rows and columns, and by changing the - number of rows or columns spanned by widgets. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const - - Returns the index of the item in the layout that covers the given \a position. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const - - Returns the item in the layout that occupies the specified \a row and \a column in the layout. - - Currently, this only applies to grid layouts. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) - - Adjusts the indicator for the item specified by \a index so that - it lies at the given \a position on the form. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerContainerExtension - \brief The QDesignerContainerExtension class allows you to add pages to - a custom multi-page container in Qt Designer's workspace. - \inmodule QtDesigner - - QDesignerContainerExtension provide an interface for creating - custom container extensions. A container extension consists of a - collection of functions that \QD needs to manage a multi-page - container plugin, and a list of the container's pages. - - \image containerextension-example.png - - \warning This is \e not an extension for container plugins in - general, only custom \e multi-page containers. - - To create a container extension, your extension class must inherit - from both QObject and QDesignerContainerExtension. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 - - Since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement several functions to enable \QD to manage a - custom multi-page container widget: \QD uses count() to keep track - of the number pages in your container, widget() to return the page - at a given index in the list of the container's pages, and - currentIndex() to return the list index of the selected page. \QD - uses the addWidget() function to add a given page to the - container, expecting it to be appended to the list of pages, while - it expects the insertWidget() function to add a given page to the - container by inserting it at a given index. - - In \QD the extensions are not created until they are - required. For that reason you must also create a - QExtensionFactory, i.e a class that is able to make an instance of - your extension, and register it using \QD's \l - {QExtensionManager}{extension manager}. - - When a container extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a container - extension, is found. This factory will then create the extension - for the plugin. - - There are four available types of extensions in \QD: - QDesignerContainerExtension , QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. - \QD's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a container extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 - - For a complete example using the QDesignerContainerExtension - class, see the \l {designer/containerextension}{Container - Extension example}. The example shows how to create a custom - multi-page plugin for \QD. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerContainerExtension::~QDesignerContainerExtension() - - Destroys the extension. -*/ - -/*! - \fn int QDesignerContainerExtension::count() const - - Returns the number of pages in the container. -*/ - -/*! - \fn QWidget *QDesignerContainerExtension::widget(int index) const - - Returns the page at the given \a index in the extension's list of - pages. - - \sa addWidget(), insertWidget() -*/ - -/*! - \fn int QDesignerContainerExtension::currentIndex() const - - Returns the index of the currently selected page in the - container. - - \sa setCurrentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::setCurrentIndex(int index) - - Sets the currently selected page in the container to be the - page at the given \a index in the extension's list of pages. - - \sa currentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::addWidget(QWidget *page) - - Adds the given \a page to the container by appending it to the - extension's list of pages. - - \sa insertWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) - - Adds the given \a page to the container by inserting it at the - given \a index in the extension's list of pages. - - \sa addWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::remove(int index) - - Removes the page at the given \a index from the extension's list - of pages. - - \sa addWidget(), insertWidget() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerTaskMenuExtension - \brief The QDesignerTaskMenuExtension class allows you to add custom - menu entries to Qt Designer's task menu. - \inmodule QtDesigner - - QDesignerTaskMenuExtension provides an interface for creating - custom task menu extensions. It is typically used to create task - menu entries that are specific to a plugin in \QD. - - \QD uses the QDesignerTaskMenuExtension to feed its task - menu. Whenever a task menu is requested, \QD will query - for the selected widget's task menu extension. - - \image taskmenuextension-example-faded.png - - A task menu extension is a collection of QActions. The actions - appear as entries in the task menu when the plugin with the - specified extension is selected. The image above shows the custom - \gui {Edit State...} action which appears in addition to \QD's - default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. - - To create a custom task menu extension, your extension class must - inherit from both QObject and QDesignerTaskMenuExtension. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 - - Since we are implementing an interface, we must ensure that it - is made known to the meta-object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement the taskActions() function to return a list - of actions that will be included in \QD task menu. Optionally, you - can reimplement the preferredEditAction() function to set the - action that is invoked when selecting your plugin and pressing - \key F2. The preferred edit action must be one of the actions - returned by taskActions() and, if it's not defined, pressing the - \key F2 key will simply be ignored. - - In \QD, extensions are not created until they are required. A - task menu extension, for example, is created when you click the - right mouse button over a widget in \QD's workspace. For that - reason you must also construct an extension factory, using either - QExtensionFactory or a subclass, and register it using \QD's - \l {QExtensionManager}{extension manager}. - - When a task menu extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until it finds one that is able to create a task menu - extension for the selected widget. This factory will then make an - instance of the extension. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. - \QD's behavior is the same whether the requested extension is - associated with a container, a member sheet, a property sheet or a - task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a task menu extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 - - For a complete example using the QDesignerTaskMenuExtension class, - see the \l {designer/taskmenuextension}{Task Menu Extension - example}. The example shows how to create a custom widget plugin - for \QD, and how to to use the QDesignerTaskMenuExtension - class to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() - - Destroys the task menu extension. -*/ - -/*! - \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const - - Returns the action that is invoked when selecting a plugin with - the specified extension and pressing \key F2. - - The action must be one of the actions returned by taskActions(). -*/ - -/*! - \fn QList QDesignerTaskMenuExtension::taskActions() const - - Returns the task menu extension as a list of actions which will be - included in \QD's task menu when a plugin with the specified - extension is selected. - - The function must be reimplemented to add actions to the list. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetCollectionInterface - - \brief The QDesignerCustomWidgetCollectionInterface class allows - you to include several custom widgets in one single library. - - \inmodule QtDesigner - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - QDesignerCustomWidgetCollectionInterface contains one single - function returning a list of the collection's - QDesignerCustomWidgetInterface objects. For example, if you have - several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and - \c CustomWidgetThree, the class definition may look like this: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 - - In the class constructor you add the interfaces to your custom - widgets to the list which you return in the customWidgets() - function: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 - - Note that instead of exporting each custom widget plugin using the - Q_EXPORT_PLUGIN2() macro, you export the entire collection. The - Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct - the custom widgets. Without this macro, there is no way for \QD to - use them. - - \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for - Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { - - Destroys the custom widget collection interface. -*/ - -/*! - \fn QList QDesignerCustomWidgetCollectionInterface::customWidgets() const - - Returns a list of interfaces to the collection's custom widgets. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetInterface - - \brief The QDesignerCustomWidgetInterface class enables Qt Designer - to access and construct custom widgets. - - \inmodule QtDesigner - - QDesignerCustomWidgetInterface provides a custom widget with an - interface. The class contains a set of functions that must be subclassed - to return basic information about the widget, such as its class name and - the name of its header file. Other functions must be implemented to - initialize the plugin when it is loaded, and to construct instances of - the custom widget for \QD to use. - - When implementing a custom widget you must subclass - QDesignerCustomWidgetInterface to expose your widget to \QD. For - example, this is the declaration for the plugin used in the - \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that - enables an analog clock custom widget to be used by \QD: - - \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 - - Note that the only part of the class definition that is specific - to this particular custom widget is the class name. In addition, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - After \QD loads a custom widget plugin, it calls the interface's - initialize() function to enable it to set up any resources that it - may need. This function is called with a QDesignerFormEditorInterface - parameter that provides the plugin with a gateway to all of \QD's API. - - \QD constructs instances of the custom widget by calling the plugin's - createWidget() function with a suitable parent widget. Plugins must - construct and return an instance of a custom widget with the specified - parent widget. - - In the implementation of the class you must remember to export - your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() - macro. For example, if a library called \c libcustomwidgetplugin.so - (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget - class called \c MyCustomWidget, we can export it by adding the - following line to the file containing the plugin implementation: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 - - This macro ensures that \QD can access and construct the custom widget. - Without this macro, there is no way for \QD to use it. - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - \warning If your custom widget plugin contains QVariant - properties, be aware that only the following \l - {QVariant::Type}{types} are supported: - - \list - \o QVariant::ByteArray - \o QVariant::Bool - \o QVariant::Color - \o QVariant::Cursor - \o QVariant::Date - \o QVariant::DateTime - \o QVariant::Double - \o QVariant::Int - \o QVariant::Point - \o QVariant::Rect - \o QVariant::Size - \o QVariant::SizePolicy - \o QVariant::String - \o QVariant::Time - \o QVariant::UInt - \endlist - - For a complete example using the QDesignerCustomWidgetInterface - class, see the \l {designer/customwidgetplugin}{Custom Widget - Example}. The example shows how to create a custom widget plugin - for \QD. - - \sa QDesignerCustomWidgetCollectionInterface {Creating Custom - Widgets for Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() - - Destroys the custom widget interface. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::name() const - - Returns the class name of the custom widget supplied by the interface. - - The name returned \e must be identical to the class name used for the - custom widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::group() const - - Returns the name of the group to which the custom widget belongs. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::toolTip() const - - Returns a short description of the widget that can be used by \QD - in a tool tip. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::whatsThis() const - - Returns a description of the widget that can be used by \QD in - "What's This?" help for the widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::includeFile() const - - Returns the path to the include file that \l uic uses when - creating code for the custom widget. -*/ - -/*! - \fn QIcon QDesignerCustomWidgetInterface::icon() const - - Returns the icon used to represent the custom widget in \QD's - widget box. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isContainer() const - - Returns true if the custom widget is intended to be used as a - container; otherwise returns false. - - Most custom widgets are not used to hold other widgets, so their - implementations of this function will return false, but custom - containers will return true to ensure that they behave correctly - in \QD. -*/ - -/*! - \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) - - Returns a new instance of the custom widget, with the given \a - parent. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isInitialized() const - - Returns true if the widget has been initialized; otherwise returns - false. - - \sa initialize() -*/ - -/*! - \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) - - Initializes the widget for use with the specified \a formEditor - interface. - - \sa isInitialized() -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::domXml() const - - Returns the XML that is used to describe the custom widget's - properties to \QD. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::codeTemplate() const - - This function is reserved for future use by \QD. - - \omit - Returns the code template that \QD includes in forms that contain - the custom widget when they are saved. - \endomit -*/ - -/*! - \macro QDESIGNER_WIDGET_EXPORT - \relates QDesignerCustomWidgetInterface - \since 4.1 - - This macro is used when defining custom widgets to ensure that they are - correctly exported from plugins for use with \QD. - - On some platforms, the symbols required by \QD to create new widgets - are removed from plugins by the build system, making them unusable. - Using this macro ensures that the symbols are retained on those platforms, - and has no side effects on other platforms. - - For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} - example exports a custom widget class with the following declaration: - - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 - \dots - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 - - \sa {Creating Custom Widgets for Qt Designer} -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerDnDItemInterface - \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items - during a drag and drop operation. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerDnDItemInterface::DropType - - This enum describes the result of a drag and drop operation. - - \value MoveDrop The item was moved. - \value CopyDrop The item was copied. -*/ - -/*! - \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() - - Constructs a new interface to a drag and drop item. -*/ - -/*! - \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() - - Destroys the interface to the item. -*/ - -/*! - \fn DomUI *QDesignerDnDItemInterface::domUi() const - - Returns a user interface object for the item. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::widget() const - - Returns the widget being copied or moved in the drag and drop operation. - - \sa source() -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::decoration() const - - Returns the widget used to represent the item. -*/ - -/*! - \fn QPoint QDesignerDnDItemInterface::hotSpot() const - - Returns the cursor's hotspot. - - \sa QDrag::hotSpot() -*/ - -/*! - \fn DropType QDesignerDnDItemInterface::type() const - - Returns the type of drag and drop operation in progress. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::source() const - - Returns the widget that is the source of the drag and drop operation; i.e. the original - container of the widget being dragged. - - \sa widget() -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerIconCacheInterface - \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. - \inmodule QtDesigner - \internal -*/ - -/*! - \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) - - Constructs a new interface with the given \a parent. -*/ - -/*! - \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) - - Returns the icon associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToPixmap() -*/ - -/*! - \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) - - Returns the pixmap associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToIcon() -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const - - Returns the file path associated with the given \a icon. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const - - Returns the path to the resource file that refers to the specified \a icon. The resource - path refers to a local file. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const - - Returns the file path associated with the given \a pixmap. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const - - Returns the path to the resource file that refers to the specified \a pixmap. The resource - path refers to a local file. -*/ - -/*! - \fn QList QDesignerIconCacheInterface::pixmapList() const - - Returns a list of pixmaps for the icons provided by the icon cache. -*/ - -/*! - \fn QList QDesignerIconCacheInterface::iconList() const - - Returns a list of icons provided by the icon cache. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const - - Returns a path to a resource specified by the \a filePath within - the resource file located at \a qrcPath. If \a workingDirectory is - a valid path to a directory, the path returned will be relative to - that directory; otherwise an absolute path is returned. - - \omit - ### Needs checking - \endomit -*/ - - -// Doc: Interface only - -/*! - \class QDesignerPropertySheetExtension - - \brief The QDesignerPropertySheetExtension class allows you to - manipulate a widget's properties which is displayed in Qt - Designer's property editor. - - \sa QDesignerDynamicPropertySheetExtension - - \inmodule QtDesigner - - QDesignerPropertySheetExtension provides a collection of functions that - are typically used to query a widget's properties, and to - manipulate the properties' appearance in the property editor. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 - - Note that if you change the value of a property using the - QDesignerPropertySheetExtension::setProperty() function, the undo - stack is not updated. To ensure that a property's value can be - reverted using the undo stack, you must use the - QDesignerFormWindowCursorInterface::setProperty() function, or its - buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The property sheet, or any other extension, can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default property sheet which populates \QD's - property editor with the widget's properties (i.e the ones defined - with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension - also provides an interface for creating custom property sheet - extensions. - - \warning \QD uses the QDesignerPropertySheetExtension to feed its - property editor. Whenever a widget is selected in its workspace, - \QD will query for the widget's property sheet extension. If the - selected widget has an implemented property sheet extension, this - extension will override the default property sheet. - - To create a property sheet extension, your extension class must - inherit from both QObject and - QDesignerPropertySheetExtension. Then, since we are implementing - an interface, we must ensure that it's made known to the meta - object system using the Q_INTERFACES() macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 - - This enables \QD to use qobject_cast() to query for supported - interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a property sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a property sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a property - sheet extension for the selected widget, is found. This factory - will then make an instance of the extension. If no such factory - can be found, \QD will use the default property sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt - Designer's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a property sheet extension extension as well. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 - - For a complete example using an extension class, see the \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() - - Destroys the property sheet extension. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::count() const - - Returns the selected widget's number of properties. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const - - Returns the index for a given property \a name. - - \sa propertyName() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyName(int index) const - - Returns the name of the property at the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const - - Returns the property group for the property at the given \a index. - - \QD's property editor supports property groups, i.e. sections of - related properties. A property can be related to a group using the - setPropertyGroup() function. The default group of any property is - the name of the class that defines it. For example, the - QObject::objectName property appears within the QObject property - group. - - \sa indexOf(), setPropertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) - - Sets the property group for the property at the given \a index to - \a group. - - Relating a property to a group makes it appear within that group's - section in the property editor. The default property group of any - property is the name of the class that defines it. For example, - the QObject::objectName property appears within the QObject - property group. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::hasReset(int index) const - - Returns true if the property at the given \a index has a reset - button in \QD's property editor, otherwise false. - - \sa indexOf(), reset() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::reset(int index) - - Resets the value of the property at the given \a index, to the - default value. Returns true if a default value could be found, otherwise false. - - \sa indexOf(), hasReset(), isChanged() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isVisible(int index) const - - Returns true if the property at the given \a index is visible in - \QD's property editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the property at the given \a index is - visible in \QD's property editor; otherwise the property is - hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const - - Returns true if the property at the given \a index is an attribute, - which will be \e excluded from the UI file, otherwise false. - - \sa indexOf(), setAttribute() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) - - If \a attribute is true, the property at the given \a index is - made an attribute which will be \e excluded from the UI file; - otherwise it will be included. - - \sa indexOf(), isAttribute() -*/ - -/*! - \fn QVariant QDesignerPropertySheetExtension::property(int index) const - - Returns the value of the property at the given \a index. - - \sa indexOf(), setProperty(), propertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) - - Sets the \a value of the property at the given \a index. - - \warning If you change the value of a property using this - function, the undo stack is not updated. To ensure that a - property's value can be reverted using the undo stack, you must - use the QDesignerFormWindowCursorInterface::setProperty() - function, or its buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isChanged(int index) const - - Returns true if the value of the property at the given \a index - differs from the property's default value, otherwise false. - - \sa indexOf(), setChanged(), reset() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) - - Sets whether the property at the given \a index is different from - its default value, or not, depending on the \a changed parameter. - - \sa indexOf(), isChanged() -*/ - -// Doc: Interface only - -/*! - \class QDesignerDynamicPropertySheetExtension - - \brief The QDesignerDynamicPropertySheetExtension class allows you to - manipulate a widget's dynamic properties in Qt Designer's property editor. - - \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} - - \inmodule QtDesigner - \since 4.3 -*/ - -/*! - \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() - - Destroys the dynamic property sheet extension. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const - - Returns true if the widget supports dynamic properties; otherwise returns false. -*/ - -/*! - \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) - - Adds a dynamic property named \a propertyName and sets its value to \a value. - Returns the index of the property if it was added successfully; otherwise returns -1 to - indicate failure. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) - - Removes the dynamic property at the given \a index. - Returns true if the operation succeeds; otherwise returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const - - Returns true if the property at the given \a index is a dynamic property; otherwise - returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const - - Returns true if \a propertyName is a valid, unique name for a dynamic - property; otherwise returns false. - -*/ diff --git a/doc/src/qtendian.qdoc b/doc/src/qtendian.qdoc deleted file mode 100644 index dcffb5d..0000000 --- a/doc/src/qtendian.qdoc +++ /dev/null @@ -1,168 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Endian Conversion Functions - \ingroup architecture - \brief The header provides functions to convert between - little and big endian representations of numbers. -*/ - -/*! - \fn T qFromBigEndian(const uchar *src) - \since 4.3 - \relates - - Reads a big-endian number from memory location \a src and returns the number in the - host byte order representation. - On CPU architectures where the host byte order is little-endian (such as x86) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromLittleEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromBigEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from big-endian byte order and returns the number in host byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn T qFromLittleEndian(const uchar *src) - \since 4.3 - \relates - - Reads a little-endian number from memory location \a src and returns the number in - the host byte order representation. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromBigEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromLittleEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from little-endian byte order and returns the number in host byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToBigEndian(T src, uchar *dest) - \since 4.3 - \relates - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in big-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qToBigEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from host byte order and returns the number in big-endian byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToLittleEndian(T src, uchar *dest) - \since 4.3 - \relates - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in little-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToBigEndian() -*/ -/*! - \fn T qToLittleEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from host byte order and returns the number in little-endian byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ - diff --git a/doc/src/qtestevent.qdoc b/doc/src/qtestevent.qdoc deleted file mode 100644 index 2e111b3..0000000 --- a/doc/src/qtestevent.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QTestEventList - \inmodule QtTest - - \brief The QTestEventList class provides a list of GUI events. - - QTestEventList inherits from QList, and provides - convenience functions for populating the list. - - A QTestEventList can be populated with GUI events that can be - stored as test data for later usage, or be replayed on any - QWidget. - - Example: - \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 - - The example above simulates the user entering the character \c a - followed by a backspace, waiting for 200 milliseconds and - repeating it. -*/ - -/*! \fn QTestEventList::QTestEventList() - - Constructs an empty QTestEventList. -*/ - -/*! \fn QTestEventList::QTestEventList(const QTestEventList &other) - - Constructs a new QTestEventList as a copy of \a other. -*/ - -/*! \fn QTestEventList::~QTestEventList() - - Empties the list and destroys all stored events. -*/ - -/*! \fn void QTestEventList::clear() - - Removes all events from the list. -*/ - -/*! \fn void QTestEventList::addKeyClick(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key click to the list. The event will simulate the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() -*/ - -/*! \fn void QTestEventList::addKeyPress(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key press to the list. The event will press the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key release to the list. The event will release the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() - -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addKeyClick(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key click to the list. The event will simulate the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() - -*/ - -/*! \fn void QTestEventList::addKeyPress(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key press to the list. The event will press the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key release to the list. The event will release the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() -*/ - -/*! \fn void QTestEventList::addKeyClicks(const QString &keys, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds new keyboard entries to the list. The event will press the \a keys with the \a modifiers and wait \a msecs milliseconds between each key. - - \sa QTest::keyClicks() -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addDelay(int msecs) - - Adds a \a msecs milliseconds delay. - - \sa QTest::qWait() -*/ - -/*! \fn void QTestEventList::simulate(QWidget *w) - - Simulates the events from the list one by one on the widget \a w. - For an example, please read the \l QTestEventList class documentation. -*/ - -/*! \fn void QTestEventList::addMousePress(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse press to the list. The event will press the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseRelease(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse release to the list. The event will release the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseRelease() -*/ -/*! \fn void QTestEventList::addMouseClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse click to the list. The event will click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseClick() -*/ -/*! \fn void QTestEventList::addMouseDClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a double mouse click to the list. The event will double click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseMove(QPoint pos = QPoint(), int delay=-1) - - Adds a mouse move to the list. The event will move the mouse to the position \a pos. If a \a delay (in milliseconds) is set, the test will wait after moving the mouse. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ - diff --git a/doc/src/qvarlengtharray.qdoc b/doc/src/qvarlengtharray.qdoc deleted file mode 100644 index ac6bb6e..0000000 --- a/doc/src/qvarlengtharray.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QVarLengthArray - \brief The QVarLengthArray class provides a low-level variable-length array. - - \ingroup tools - \reentrant - - The C++ language doesn't support variable-length arrays on the stack. - For example, the following code won't compile: - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 - - The alternative is to allocate the array on the heap (with - \c{new}): - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 - - However, if myfunc() is called very frequently from the - application's inner loop, heap allocation can be a major source - of slowdown. - - QVarLengthArray is an attempt to work around this gap in the C++ - language. It allocates a certain number of elements on the stack, - and if you resize the array to a larger size, it automatically - uses the heap instead. Stack allocation has the advantage that - it is much faster than heap allocation. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 - - In the example above, QVarLengthArray will preallocate 1024 - elements on the stack and use them unless \c{n + 1} is greater - than 1024. If you omit the second template argument, - QVarLengthArray's default of 256 is used. - - QVarLengthArray's value type must be an \l{assignable data type}. - This covers most data types that are commonly used, but the - compiler won't let you, for example, store a QWidget as a value; - instead, store a QWidget *. - - QVarLengthArray, like QVector, provides a resizable array data - structure. The main differences between the two classes are: - - \list - \o QVarLengthArray's API is much more low-level. It provides no - iterators and lacks much of QVector's functionality. - - \o QVarLengthArray doesn't initialize the memory if the value is - a basic type. (QVector always does.) - - \o QVector uses \l{implicit sharing} as a memory optimization. - QVarLengthArray doesn't provide that feature; however, it - usually produces slightly better performance due to reduced - overhead, especially in tight loops. - \endlist - - In summary, QVarLengthArray is a low-level optimization class - that only makes sense in very specific cases. It is used a few - places inside Qt and was added to Qt's public API for the - convenience of advanced users. - - \sa QVector, QList, QLinkedList -*/ - -/*! \fn QVarLengthArray::QVarLengthArray(int size) - - Constructs an array with an initial size of \a size elements. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), the elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. -*/ - -/*! \fn QVarLengthArray::~QVarLengthArray() - - Destroys the array. -*/ - -/*! \fn int QVarLengthArray::size() const - - Returns the number of elements in the array. - - \sa isEmpty(), resize() -*/ - -/*! \fn int QVarLengthArray::count() const - - Same as size(). - - \sa isEmpty(), resize() -*/ - -/*! \fn bool QVarLengthArray::isEmpty() const - - Returns true if the array has size 0; otherwise returns false. - - \sa size(), resize() -*/ - -/*! \fn void QVarLengthArray::clear() - - Removes all the elements from the array. - - Same as resize(0). -*/ - -/*! \fn void QVarLengthArray::resize(int size) - - Sets the size of the array to \a size. If \a size is greater than - the current size, elements are added to the end. If \a size is - less than the current size, elements are removed from the end. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), new elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. - - \sa size() -*/ - -/*! \fn int QVarLengthArray::capacity() const - - Returns the maximum number of elements that can be stored in the - array without forcing a reallocation. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will rarely ever - need to call this function. If you want to know how many items are - in the array, call size(). - - \sa reserve() -*/ - -/*! \fn void QVarLengthArray::reserve(int size) - - Attempts to allocate memory for at least \a size elements. If you - know in advance how large the array can get, you can call this - function and if you call resize() often, you are likely to get - better performance. If \a size is an underestimate, the worst - that will happen is that the QVarLengthArray will be a bit - slower. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will - rarely ever need to call this function. If you want to change the - size of the array, call resize(). - - \sa capacity() -*/ - -/*! \fn T &QVarLengthArray::operator[](int i) - - Returns a reference to the item at index position \a i. - - \a i must be a valid index position in the array (i.e., 0 <= \a i - < size()). - - \sa data() -*/ - -/*! \fn const T &QVarLengthArray::operator[](int i) const - - \overload -*/ - - -/*! - \fn void QVarLengthArray::append(const T &t) - - Appends item \a t to the array, extending the array if necessary. - - \sa removeLast() -*/ - - -/*! - \fn inline void QVarLengthArray::removeLast() - \since 4.5 - - Decreases the size of the array by one. The allocated size is not changed. - - \sa append() -*/ - -/*! - \fn void QVarLengthArray::append(const T *buf, int size) - - Appends \a size amount of items referenced by \a buf to this array. -*/ - - -/*! \fn T *QVarLengthArray::data() - - Returns a pointer to the data stored in the array. The pointer can - be used to access and modify the items in the array. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 - - The pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa constData(), operator[]() -*/ - -/*! \fn const T *QVarLengthArray::data() const - - \overload -*/ - -/*! \fn const T *QVarLengthArray::constData() const - - Returns a const pointer to the data stored in the array. The - pointer can be used to access the items in the array. The - pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa data(), operator[]() -*/ - -/*! \fn QVarLengthArray &QVarLengthArray::operator=(const QVarLengthArray &other) - Assigns \a other to this array and returns a reference to this array. - */ - -/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray &other) - Constructs a copy of \a other. - */ - diff --git a/doc/src/qwaitcondition.qdoc b/doc/src/qwaitcondition.qdoc deleted file mode 100644 index ae94e35..0000000 --- a/doc/src/qwaitcondition.qdoc +++ /dev/null @@ -1,188 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QWaitCondition - \brief The QWaitCondition class provides a condition variable for - synchronizing threads. - - \threadsafe - - \ingroup thread - \ingroup environment - - QWaitCondition allows a thread to tell other threads that some - sort of condition has been met. One or many threads can block - waiting for a QWaitCondition to set a condition with wakeOne() or - wakeAll(). Use wakeOne() to wake one randomly selected condition or - wakeAll() to wake them all. - - For example, let's suppose that we have three tasks that should - be performed whenever the user presses a key. Each task could be - split into a thread, each of which would have a - \l{QThread::run()}{run()} body like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0 - - Here, the \c keyPressed variable is a global variable of type - QWaitCondition. - - A fourth thread would read key presses and wake the other three - threads up every time it receives one, like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1 - - The order in which the three threads are woken up is undefined. - Also, if some of the threads are still in \c do_something() when - the key is pressed, they won't be woken up (since they're not - waiting on the condition variable) and so the task will not be - performed for that key press. This issue can be solved using a - counter and a QMutex to guard it. For example, here's the new - code for the worker threads: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2 - - Here's the code for the fourth thread: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3 - - The mutex is necessary because the results of two threads - attempting to change the value of the same variable - simultaneously are unpredictable. - - Wait conditions are a powerful thread synchronization primitive. - The \l{threads/waitconditions}{Wait Conditions} example shows how - to use QWaitCondition as an alternative to QSemaphore for - controlling access to a circular buffer shared by a producer - thread and a consumer thread. - - \sa QMutex, QSemaphore, QThread, {Wait Conditions Example} -*/ - -/*! - \fn QWaitCondition::QWaitCondition() - - Constructs a new wait condition object. -*/ - -/*! - \fn QWaitCondition::~QWaitCondition() - - Destroys the wait condition object. -*/ - -/*! - \fn void QWaitCondition::wakeOne() - - Wakes one thread waiting on the wait condition. The thread that - is woken up depends on the operating system's scheduling - policies, and cannot be controlled or predicted. - - If you want to wake up a specific thread, the solution is - typically to use different wait conditions and have different - threads wait on different conditions. - - \sa wakeAll() -*/ - -/*! - \fn void QWaitCondition::wakeAll() - - Wakes all threads waiting on the wait condition. The order in - which the threads are woken up depends on the operating system's - scheduling policies and cannot be controlled or predicted. - - \sa wakeOne() -*/ - -/*! - \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time) - - Releases the locked \a mutex and waits on the wait condition. The - \a mutex must be initially locked by the calling thread. If \a - mutex is not in a locked state, this function returns - immediately. If \a mutex is a recursive mutex, this function - returns immediately. The \a mutex will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The mutex will be returned to the same locked state. This - function is provided to allow the atomic transition from the - locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ - -/*! - \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time) - \since 4.4 - - Releases the locked \a readWriteLock and waits on the wait - condition. The \a readWriteLock must be initially locked by the - calling thread. If \a readWriteLock is not in a locked state, this - function returns immediately. The \a readWriteLock must not be - locked recursively, otherwise this function will not release the - lock properly. The \a readWriteLock will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The \a readWriteLock will be returned to the same locked - state. This function is provided to allow the atomic transition - from the locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ -- cgit v0.12