From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qptrlist.html | 741 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 741 insertions(+) create mode 100644 doc/html/qptrlist.html (limited to 'doc/html/qptrlist.html') diff --git a/doc/html/qptrlist.html b/doc/html/qptrlist.html new file mode 100644 index 000000000..208482d61 --- /dev/null +++ b/doc/html/qptrlist.html @@ -0,0 +1,741 @@ + + + + + +TQPtrList Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQPtrList Class Reference

+ +

The TQPtrList class is a template class that provides a list. +More... +

#include <qptrlist.h> +

Inherits TQPtrCollection. +

Inherited by TQObjectList, TQSortedList, and TQStrList. +

List of all member functions. +

Public Members

+ +

Important Inherited Members

+ +

Protected Members

+ +

Detailed Description

+ + +The TQPtrList class is a template class that provides a list. +

+ +

+

TQValueList is an STL-compatible alternative to this class. +

Define a template instance TQPtrList<X> to create a list that +operates on pointers to X (X*). +

The list class is indexable and has a current + index and a current item. 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(). +

+Example: +

+    class Employee
+    {
+    public:
+        Employee() : sn( 0 ) { }
+        Employee( const TQString& forename, const TQString& surname, int salary )
+            : fn( forename ), sn( surname ), sal( salary )
+        { }
+
+        void setSalary( int salary ) { sal = salary; }
+
+        TQString forename() const { return fn; }
+        TQString surname() const { return sn; }
+        int salary() const { return sal; }
+
+    private:
+        TQString fn;
+        TQString sn;
+        int sal;
+    };
+
+    TQPtrList<Employee> list;
+    list.setAutoDelete( TRUE ); // the list owns the objects
+
+    list.append( new Employee("John", "Doe", 50000) );
+    list.append( new Employee("Jane", "Williams", 80000) );
+    list.append( new Employee("Tom", "Jones", 60000) );
+
+    Employee *employee;
+    for ( employee = list.first(); employee; employee = list.next() )
+        cout << employee->surname().latin1() << ", " <<
+                employee->forename().latin1() << " earns " <<
+                employee->salary() << endl;
+    cout << endl;
+
+    // very inefficient for big lists
+    for ( uint i = 0; i < list.count(); ++i )
+        if ( list.at(i) )
+            cout << list.at( i )->surname().latin1() << endl;
+
+ +

The output is +

+    Doe, John earns 50000
+    Williams, Jane earns 80000
+    Jones, Tom earns 60000
+
+    Doe
+    Williams
+    Jones
+
+ +

TQPtrList has several member functions for traversing the list, but +using a TQPtrListIterator 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 TQPtrCollection::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 +TQPtrCollection::deleteItem() is called. TQPtrList'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 void* in an internal TQLNode, which +also holds pointers to the next and previous list items. The +functions currentNode(), removeNode(), and takeNode() operate +directly on the TQLNode, but they should be used with care. The +data component of the node is available through TQLNode::getData(). +

The TQStrList class defined in qstrlist.h is a list of char*. +It reimplements newItem(), deleteItem() and compareItems(). (But +see TQStringList for a list of Unicode TQStrings.) +

See also TQPtrListIterator, Collection Classes, and Non-GUI Classes. + +

Member Function Documentation

+

TQPtrList::TQPtrList () +

+ +

Constructs an empty list. + +

TQPtrList::TQPtrList ( const TQPtrList<type> & list ) +

+ +

Constructs a copy of list. +

Each item in list is appended to this +list. Only the pointers are copied (shallow copy). + +

TQPtrList::~TQPtrList () +

+ +

Removes all items from the list and destroys the list. +

All list iterators that access this list will be reset. +

See also setAutoDelete(). + +

void TQPtrList::append ( const type * item ) +

+ +

Inserts the item at the end of the list. +

The inserted item becomes the current list item. This is +equivalent to insert( count(), item ). +

item must not be 0. +

See also insert(), current(), and prepend(). + +

Examples: customlayout/border.cpp, customlayout/card.cpp, customlayout/flow.cpp, grapher/grapher.cpp, listviews/listviews.cpp, listviews/listviews.h, and qwerty/qwerty.cpp. +

type * TQPtrList::at ( uint index ) +

+ +

Returns a pointer to the item at position index in the list, or +0 if the index is out of range. +

Sets the current list item to this item if index is valid. The +valid range is 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 index. +

See also current(). + +

Examples: customlayout/border.cpp, customlayout/card.cpp, customlayout/flow.cpp, dirview/dirview.cpp, mdi/application.cpp, and qwerty/qwerty.cpp. +

int TQPtrList::at () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns the index of the current list item. The returned value is +-1 if the current item is 0. +

See also current(). + +

bool TQPtrCollection::autoDelete () const +

+ +

Returns the setting of the auto-delete option. The default is FALSE. +

See also setAutoDelete(). + +

void TQPtrList::clear () [virtual] +

+ +

Removes all items from the list. +

The removed items are deleted if auto-deletion is enabled. +

All list iterators that access this list will be reset. +

See also remove(), take(), and setAutoDelete(). + +

Reimplemented from TQPtrCollection. +

int TQPtrList::compareItems ( TQPtrCollection::Item item1, TQPtrCollection::Item item2 ) [virtual protected] +

+ +

This virtual function compares two list items. +

Returns: +

+

This function returns int rather than bool so that +reimplementations can return three values and use it to sort by: +

+

inSort() retquires 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. + +

uint TQPtrList::contains ( const type * item ) const +

+ +

Returns the number of occurrences of item in the list. +

The compareItems() function is called when looking for the 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. +

See also containsRef() and compareItems(). + +

uint TQPtrList::containsRef ( const type * item ) const +

+ +

Returns the number of occurrences of item in the list. +

Calling this function is much faster than contains() because +contains() compares item with each list item using +compareItems(), whereas his function only compares the pointers. +

This function does not affect the current list item. +

See also contains(). + +

uint TQPtrList::count () const [virtual] +

+ +

Returns the number of items in the list. +

See also isEmpty(). + +

Examples: customlayout/border.cpp, customlayout/card.cpp, customlayout/flow.cpp, dirview/dirview.cpp, grapher/grapher.cpp, mdi/application.cpp, and qwerty/qwerty.cpp. +

Reimplemented from TQPtrCollection. +

type * TQPtrList::current () const +

+ +

Returns a pointer to the current list item. The current item may +be 0 (implies that the current index is -1). +

See also at(). + +

TQLNode * TQPtrList::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. +

See also removeNode(), takeNode(), and current(). + +

int TQPtrList::find ( const type * item ) +

+ +

Finds the first occurrence of 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(). +

See also findNext(), findRef(), compareItems(), and current(). + +

int TQPtrList::findNext ( const type * item ) +

+ +

Finds the next occurrence of 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(). +

See also find(), findNextRef(), compareItems(), and current(). + +

int TQPtrList::findNextRef ( const type * item ) +

+ +

Finds the next occurrence of 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 item with each list item using +compareItems(), whereas this function only compares the pointers. +

See also findRef(), findNext(), and current(). + +

int TQPtrList::findRef ( const type * item ) +

+ +

Finds the first occurrence of 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 item with each list item using compareItems(), whereas +this function only compares the pointers. +

See also findNextRef(), find(), and current(). + +

type * TQPtrList::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. +

See also getFirst(), last(), next(), prev(), and current(). + +

Examples: grapher/grapher.cpp, listviews/listviews.h, and showimg/showimg.cpp. +

type * TQPtrList::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. +

See also first() and getLast(). + +

type * TQPtrList::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. +

See also last() and getFirst(). + +

void TQPtrList::inSort ( const type * item ) +

+ +

Inserts the 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. +

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. +

See also insert(), compareItems(), current(), and sort(). + +

bool TQPtrList::insert ( uint index, const type * item ) +

+ +

Inserts the item at position index in the list. +

Returns TRUE if successful, i.e. if index is in range; +otherwise returns FALSE. The valid range is 0 to count() +(inclusively). The item is appended if index == count(). +

The inserted item becomes the current list item. +

item must not be 0. +

See also append(), current(), and replace(). + +

bool TQPtrList::isEmpty () const +

+ +

Returns TRUE if the list is empty; otherwise returns FALSE. +

See also count(). + +

type * TQPtrList::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. +

See also getLast(), first(), next(), prev(), and current(). + +

type * TQPtrList::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. +

See also first(), last(), prev(), and current(). + +

Examples: grapher/grapher.cpp, listviews/listviews.h, and showimg/showimg.cpp. +

bool TQPtrList::operator!= ( const TQPtrList<type> & list ) const +

+ +

Compares this list with list. Returns TRUE if the lists contain +different data; otherwise returns FALSE. + +

TQPtrList<type> & TQPtrList::operator= ( const TQPtrList<type> & list ) +

+ +

Assigns list to this list and returns a reference to this list. +

This list is first cleared and then each item in list is appended to this list. Only the pointers are +copied (shallow copy) unless newItem() has been reimplemented. + +

bool TQPtrList::operator== ( const TQPtrList<type> & list ) const +

+ +

Compares this list with list. Returns TRUE if the lists contain +the same data; otherwise returns FALSE. + +

void TQPtrList::prepend ( const type * item ) +

+ +

Inserts the item at the start of the list. +

The inserted item becomes the current list item. This is +equivalent to insert( 0, item ). +

item must not be 0. +

See also append(), insert(), and current(). + +

type * TQPtrList::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. +

See also first(), last(), next(), and current(). + +

TQDataStream & TQPtrList::read ( TQDataStream & s, TQPtrCollection::Item & item ) [virtual protected] +

+ +

Reads a list item from the stream s and returns a reference to +the stream. +

The default implementation sets item to 0. +

See also write(). + +

bool TQPtrList::remove ( uint index ) +

+ +

Removes the item at position index in the list. +

Returns TRUE if successful, i.e. if index is in range; +otherwise returns FALSE. The valid range is 0..(count() - 1) +inclusive. +

The removed item is deleted if auto-deletion 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. +

See also take(), clear(), setAutoDelete(), current(), and removeRef(). + +

bool TQPtrList::remove () +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

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 auto-deletion 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. +

See also take(), clear(), setAutoDelete(), current(), and removeRef(). + +

bool TQPtrList::remove ( const type * item ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Removes the first occurrence of item from the list. +

Returns TRUE if successful, i.e. if item is in the list; +otherwise returns FALSE. +

The removed item is deleted if auto-deletion 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 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. +

See also removeRef(), take(), clear(), setAutoDelete(), compareItems(), and current(). + +

bool TQPtrList::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 auto-deletion 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. +

See also removeLast(), setAutoDelete(), current(), and remove(). + +

bool TQPtrList::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 auto-deletion 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. +

See also removeFirst(), setAutoDelete(), and current(). + +

void TQPtrList::removeNode ( TQLNode * node ) +

+ +

Removes the node from the list. +

This node must exist in the list, otherwise the program may crash. +

The removed item is deleted if auto-deletion 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. +

See also takeNode(), currentNode(), remove(), and removeRef(). + +

bool TQPtrList::removeRef ( const type * item ) +

+ +

Removes the first occurrence of item from the list. +

Returns TRUE if successful, i.e. if item is in the list; +otherwise returns FALSE. +

The removed item is deleted if auto-deletion is enabled. +

Equivalent to: +

+        if ( list.findRef( item ) != -1 )
+            list.remove();
+
+ +

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. +

See also remove(), clear(), setAutoDelete(), and current(). + +

bool TQPtrList::replace ( uint index, const type * item ) +

+ +

Replaces the item at position index with the new item. +

Returns TRUE if successful, i.e. index is in the range 0 to +count()-1. +

See also append(), current(), and insert(). + +

void TQPtrCollection::setAutoDelete ( bool enable ) +

+ +

Sets the collection to auto-delete its contents if enable is +TRUE and to never delete them if enable is FALSE. +

If auto-deleting is turned on, all the items in a collection are +deleted when the collection itself is deleted. This is convenient +if the collection has the only pointer to the items. +

The default setting is FALSE, for safety. If you turn it on, be +careful about copying the collection - you might find yourself +with two collections 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. +

See also autoDelete(). + +

Examples: grapher/grapher.cpp, scribble/scribble.cpp, and table/bigtable/main.cpp. +

void TQPtrList::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 TQSortedList because it implements the +compareItems() function for you using these two operators. +

See also inSort(). + +

type * TQPtrList::take ( uint index ) +

+ +

Takes the item at position index out of the list without +deleting it (even if auto-deletion +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 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. +

See also remove(), clear(), and current(). + +

Examples: customlayout/border.cpp, customlayout/card.cpp, and customlayout/flow.cpp. +

type * TQPtrList::take () +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Takes the current item out of the list without deleting it (even +if auto-deletion 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. +

See also remove(), clear(), and current(). + +

type * TQPtrList::takeNode ( TQLNode * node ) +

+ +

Takes the node out of the list without deleting its item (even +if auto-deletion 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. +

See also removeNode() and currentNode(). + +

void TQPtrList::toVector ( TQGVector * vec ) const +

+ +

Stores all list items in the vector vec. +

The vector must be of the same item type, otherwise the result +will be undefined. + +

TQDataStream & TQPtrList::write ( TQDataStream & s, TQPtrCollection::Item item ) const [virtual protected] +

+ +

Writes a list item, item to the stream s and returns a +reference to the stream. +

The default implementation does nothing. +

See also read(). + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1