From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/qptrlist.html | 741 ------------------------------------------------- 1 file changed, 741 deletions(-) delete mode 100644 doc/html/qptrlist.html (limited to 'doc/html/qptrlist.html') diff --git a/doc/html/qptrlist.html b/doc/html/qptrlist.html deleted file mode 100644 index 0a7fa831f..000000000 --- a/doc/html/qptrlist.html +++ /dev/null @@ -1,741 +0,0 @@ - - - - - -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() 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. - -

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