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/ntqcanvas.html | 588 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 588 insertions(+) create mode 100644 doc/html/ntqcanvas.html (limited to 'doc/html/ntqcanvas.html') diff --git a/doc/html/ntqcanvas.html b/doc/html/ntqcanvas.html new file mode 100644 index 000000000..b4fab5810 --- /dev/null +++ b/doc/html/ntqcanvas.html @@ -0,0 +1,588 @@ + + + + + +TQCanvas Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQCanvas Class Reference
[canvas module]

+ +

The TQCanvas class provides a 2D area that can contain TQCanvasItem objects. +More... +

#include <ntqcanvas.h> +

Inherits TQObject. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Signals

+ +

Protected Members

+ +

Detailed Description

+ + +The TQCanvas class provides a 2D area that can contain TQCanvasItem objects. + +

+ + + + +

The TQCanvas class manages its 2D graphic area and all the canvas +items the area contains. The canvas has no visual appearance of +its own. Instead, it is displayed on screen using a TQCanvasView. +Multiple TQCanvasView widgets may be associated with a canvas to +provide multiple views of the same canvas. +

The canvas is optimized for large numbers of items, particularly +where only a small percentage of the items change at any +one time. If the entire display changes very frequently, you should +consider using your own custom TQScrollView subclass. +

TQt provides a rich +set of canvas item classes, e.g. TQCanvasEllipse, TQCanvasLine, +TQCanvasPolygon, TQCanvasPolygonalItem, TQCanvasRectangle, TQCanvasSpline, +TQCanvasSprite and TQCanvasText. You can subclass to create your own +canvas items; TQCanvasPolygonalItem is the most common base class used +for this purpose. +

Items appear on the canvas after their show() function has been called (or setVisible(TRUE)), and after +update() has been called. The canvas only shows items that are +visible, and then only if +update() is called. (By default the canvas is white and so are +canvas items, so if nothing appears try changing colors.) +

If you created the canvas without passing a width and height to +the constructor you must also call resize(). +

Although a canvas may appear to be similar to a widget with child +widgets, there are several notable differences: +

+

A canvas consists of a background, a number of canvas items organized by +x, y and z coordinates, and a foreground. A canvas item's z coordinate +can be treated as a layer number -- canvas items with a higher z +coordinate appear in front of canvas items with a lower z coordinate. +

The background is white by default, but can be set to a different color +using setBackgroundColor(), or to a repeated pixmap using +setBackgroundPixmap() or to a mosaic of smaller pixmaps using +setTiles(). Individual tiles can be set with setTile(). There +are corresponding get functions, e.g. backgroundColor() and +backgroundPixmap(). +

Note that TQCanvas does not inherit from TQWidget, even though it has some +functions which provide the same functionality as those in TQWidget. One +of these is setBackgroundPixmap(); some others are resize(), size(), +width() and height(). TQCanvasView is the widget used to display a +canvas on the screen. +

Canvas items are added to a canvas by constructing them and passing the +canvas to the canvas item's constructor. An item can be moved to a +different canvas using TQCanvasItem::setCanvas(). +

Canvas items are movable (and in the case of TQCanvasSprites, animated) +objects that inherit TQCanvasItem. Each canvas item has a position on the +canvas (x, y coordinates) and a height (z coordinate), all of which are +held as floating-point numbers. Moving canvas items also have x and y +velocities. It's possible for a canvas item to be outside the canvas +(for example TQCanvasItem::x() is greater than width()). When a canvas +item is off the canvas, onCanvas() returns FALSE and the canvas +disregards the item. (Canvas items off the canvas do not slow down any +of the common operations on the canvas.) +

Canvas items can be moved with TQCanvasItem::move(). The advance() +function moves all TQCanvasItem::animated() canvas items and +setAdvancePeriod() makes TQCanvas move them automatically on a periodic +basis. In the context of the TQCanvas classes, to `animate' a canvas item +is to set it in motion, i.e. using TQCanvasItem::setVelocity(). Animation +of a canvas item itself, i.e. items which change over time, is enabled +by calling TQCanvasSprite::setFrameAnimation(), or more generally by +subclassing and reimplementing TQCanvasItem::advance(). To detect collisions +use one of the TQCanvasItem::collisions() functions. +

The changed parts of the canvas are redrawn (if they are visible in a +canvas view) whenever update() is called. You can either call update() +manually after having changed the contents of the canvas, or force +periodic updates using setUpdatePeriod(). If you have moving objects on +the canvas, you must call advance() every time the objects should +move one step further. Periodic calls to advance() can be forced using +setAdvancePeriod(). The advance() function will call +TQCanvasItem::advance() on every item that is animated and trigger an update of the +affected areas afterwards. (A canvas item that is `animated' is simply +a canvas item that is in motion.) +

TQCanvas organizes its canvas items into chunks; these are areas on +the canvas that are used to speed up most operations. Many operations +start by eliminating most chunks (i.e. those which haven't changed) +and then process only the canvas items that are in the few interesting +(i.e. changed) chunks. A valid chunk, validChunk(), is one which is on +the canvas. +

The chunk size is a key factor to TQCanvas's speed: if there are too many +chunks, the speed benefit of grouping canvas items into chunks is +reduced. If the chunks are too large, it takes too long to process each +one. The TQCanvas constructor tries to pick a suitable size, but you +can call retune() to change it at any time. The chunkSize() function +returns the current chunk size. The canvas items always make sure +they're in the right chunks; all you need to make sure of is that +the canvas uses the right chunk size. A good rule of thumb is that +the size should be a bit smaller than the average canvas item +size. If you have moving objects, the chunk size should be a bit +smaller than the average size of the moving items. +

The foreground is normally nothing, but if you reimplement +drawForeground(), you can draw things in front of all the canvas +items. +

Areas can be set as changed with setChanged() and set unchanged with +setUnchanged(). The entire canvas can be set as changed with +setAllChanged(). A list of all the items on the canvas is returned by +allItems(). +

An area can be copied (painted) to a TQPainter with drawArea(). +

If the canvas is resized it emits the resized() signal. +

The examples/canvas application and the 2D graphics page of the +examples/demo application demonstrate many of TQCanvas's facilities. +

See also TQCanvasView, TQCanvasItem, Abstract Widget Classes, Graphics Classes, and Image Processing Classes. + +

Member Function Documentation

+

TQCanvas::TQCanvas ( TQObject * parent = 0, const char * name = 0 ) +

+Create a TQCanvas with no size. parent and name are passed to +the TQObject superclass. +

Warning: You must call resize() at some time after creation to +be able to use the canvas. + +

TQCanvas::TQCanvas ( int w, int h ) +

+Constructs a TQCanvas that is w pixels wide and h pixels high. + +

TQCanvas::TQCanvas ( TQPixmap p, int h, int v, int tilewidth, int tileheight ) +

+Constructs a TQCanvas which will be composed of h tiles +horizontally and v tiles vertically. Each tile will be an image +tilewidth by tileheight pixels taken from pixmap p. +

The pixmap p is a list of tiles, arranged left to right, (and +in the case of pixmaps that have multiple rows of tiles, top to +bottom), with tile 0 in the top-left corner, tile 1 next to the +right, and so on, e.g. +

+
0 1 2 3 +
4 5 6 7 +
+

The TQCanvas is initially sized to show exactly the given number of +tiles horizontally and vertically. If it is resized to be larger, +the entire matrix of tiles will be repeated as often as necessary +to cover the area. If it is smaller, tiles to the right and bottom +will not be visible. +

See also setTiles(). + +

TQCanvas::~TQCanvas () [virtual] +

+Destroys the canvas and all the canvas's canvas items. + +

void TQCanvas::advance () [virtual slot] +

+Moves all TQCanvasItem::animated() canvas items on the canvas and +refreshes all changes to all views of the canvas. (An `animated' +item is an item that is in motion; see setVelocity().) +

The advance takes place in two phases. In phase 0, the +TQCanvasItem::advance() function of each TQCanvasItem::animated() +canvas item is called with paramater 0. Then all these canvas +items are called again, with parameter 1. In phase 0, the canvas +items should not change position, merely examine other items on +the canvas for which special processing is required, such as +collisions between items. In phase 1, all canvas items should +change positions, ignoring any other items on the canvas. This +two-phase approach allows for considerations of "fairness", +although no TQCanvasItem subclasses supplied with TQt do anything +interesting in phase 0. +

The canvas can be configured to call this function periodically +with setAdvancePeriod(). +

See also update(). + +

TQCanvasItemList TQCanvas::allItems () +

+Returns a list of all the items in the canvas. + +

TQColor TQCanvas::backgroundColor () const +

+Returns the color set by setBackgroundColor(). By default, this is +white. +

This function is not a reimplementation of +TQWidget::backgroundColor() (TQCanvas is not a subclass of TQWidget), +but all TQCanvasViews that are viewing the canvas will set their +backgrounds to this color. +

See also setBackgroundColor() and backgroundPixmap(). + +

TQPixmap TQCanvas::backgroundPixmap () const +

+Returns the pixmap set by setBackgroundPixmap(). By default, +this is a null pixmap. +

See also setBackgroundPixmap() and backgroundColor(). + +

int TQCanvas::chunkSize () const +

+ +

Returns the chunk size of the canvas. +

See also retune(). + +

TQCanvasItemList TQCanvas::collisions ( const TQPoint & p ) const +

+Returns a list of canvas items that collide with the point p. +The list is ordered by z coordinates, from highest z coordinate +(front-most item) to lowest z coordinate (rear-most item). + +

TQCanvasItemList TQCanvas::collisions ( const TQRect & r ) const +

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

Returns a list of items which collide with the rectangle r. The +list is ordered by z coordinates, from highest z coordinate +(front-most item) to lowest z coordinate (rear-most item). + +

TQCanvasItemList TQCanvas::collisions ( const TQPointArray & chunklist, const TQCanvasItem * item, bool exact ) const +

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

Returns a list of canvas items which intersect with the chunks +listed in chunklist, excluding item. If exact is TRUE, +only those which actually collide with item are returned; otherwise canvas items +are included just for being in the chunks. +

This is a utility function mainly used to implement the simpler +TQCanvasItem::collisions() function. + +

void TQCanvas::drawArea ( const TQRect & clip, TQPainter * painter, bool dbuf = FALSE ) +

+Paints all canvas items that are in the area clip to painter, using double-buffering if dbuf is TRUE. +

e.g. to print the canvas to a printer: +

+    TQPrinter pr;
+    if ( pr.setup() ) {
+        TQPainter p(&pr);
+        canvas.drawArea( canvas.rect(), &p );
+    }
+
+ + +

Example: canvas/canvas.cpp. +

void TQCanvas::drawBackground ( TQPainter & painter, const TQRect & clip ) [virtual protected] +

+This virtual function is called for all updates of the canvas. It +renders any background graphics using the painter painter, in +the area clip. If the canvas has a background pixmap or a tiled +background, that graphic is used, otherwise the canvas is cleared +using the background color. +

If the graphics for an area change, you must explicitly call +setChanged(const TQRect&) for the result to be visible when +update() is next called. +

See also setBackgroundColor(), setBackgroundPixmap(), and setTiles(). + +

void TQCanvas::drawForeground ( TQPainter & painter, const TQRect & clip ) [virtual protected] +

+This virtual function is called for all updates of the canvas. It +renders any foreground graphics using the painter painter, in +the area clip. +

If the graphics for an area change, you must explicitly call +setChanged(const TQRect&) for the result to be visible when +update() is next called. +

The default is to draw nothing. + +

int TQCanvas::height () const +

+ +

Returns the height of the canvas, in pixels. + +

Example: canvas/canvas.cpp. +

bool TQCanvas::onCanvas ( int x, int y ) const +

+ +

Returns TRUE if the pixel position (x, y) is on the canvas; +otherwise returns FALSE. +

See also validChunk(). + +

bool TQCanvas::onCanvas ( const TQPoint & p ) const +

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

Returns TRUE if the pixel position p is on the canvas; +otherwise returns FALSE. +

See also validChunk(). + +

TQRect TQCanvas::rect () const +

+ +

Returns a rectangle the size of the canvas. + +

void TQCanvas::resize ( int w, int h ) [virtual] +

+Changes the size of the canvas to have a width of w and a +height of h. This is a slow operation. + +

Examples: canvas/canvas.cpp and chart/chartform.cpp. +

void TQCanvas::resized () [signal] +

+ +

This signal is emitted whenever the canvas is resized. Each +TQCanvasView connects to this signal to keep the scrollview's size +correct. + +

void TQCanvas::retune ( int chunksze, int mxclusters = 100 ) [virtual] +

+Change the efficiency tuning parameters to mxclusters clusters, +each of size chunksze. This is a slow operation if there are +many objects on the canvas. +

The canvas is divided into chunks which are rectangular areas chunksze wide by chunksze high. Use a chunk size which is about +the average size of the canvas items. If you choose a chunk size +which is too small it will increase the amount of calculation +required when drawing since each change will affect many chunks. +If you choose a chunk size which is too large the amount of +drawing required will increase because for each change, a lot of +drawing will be required since there will be many (unchanged) +canvas items which are in the same chunk as the changed canvas +items. +

Internally, a canvas uses a low-resolution "chunk matrix" to keep +track of all the items in the canvas. A 64x64 chunk matrix is the +default for a 1024x1024 pixel canvas, where each chunk collects +canvas items in a 16x16 pixel square. This default is also +affected by setTiles(). You can tune this default using this +function. For example if you have a very large canvas and want to +trade off speed for memory then you might set the chunk size to 32 +or 64. +

The mxclusters argument is the number of rectangular groups of +chunks that will be separately drawn. If the canvas has a large +number of small, dispersed items, this should be about that +number. Our testing suggests that a large number of clusters is +almost always best. +

+

void TQCanvas::setAdvancePeriod ( int ms ) [virtual] +

+Sets the canvas to call advance() every ms milliseconds. Any +previous setting by setAdvancePeriod() or setUpdatePeriod() is +overridden. +

If ms is less than 0 advancing will be stopped. + +

Example: canvas/main.cpp. +

void TQCanvas::setAllChanged () [virtual] +

+Marks the whole canvas as changed. +All views of the canvas will be entirely redrawn when +update() is called next. + +

void TQCanvas::setBackgroundColor ( const TQColor & c ) [virtual] +

+Sets the solid background to be the color c. +

See also backgroundColor(), setBackgroundPixmap(), and setTiles(). + +

void TQCanvas::setBackgroundPixmap ( const TQPixmap & p ) [virtual] +

+Sets the solid background to be the pixmap p repeated as +necessary to cover the entire canvas. +

See also backgroundPixmap(), setBackgroundColor(), and setTiles(). + +

void TQCanvas::setChanged ( const TQRect & area ) [virtual] +

+Marks area as changed. This area will be redrawn in all +views that are showing it when update() is called next. + +

void TQCanvas::setDoubleBuffering ( bool y ) [virtual] +

+If y is TRUE (the default) double-buffering is switched on; +otherwise double-buffering is switched off. +

Turning off double-buffering causes the redrawn areas to flicker a +little and also gives a (usually small) performance improvement. + +

Example: canvas/canvas.cpp. +

void TQCanvas::setTile ( int x, int y, int tilenum ) [virtual] +

+Sets the tile at (x, y) to use tile number tilenum, which +is an index into the tile pixmaps. The canvas will update +appropriately when update() is next called. +

The images are taken from the pixmap set by setTiles() and are +arranged left to right, (and in the case of pixmaps that have +multiple rows of tiles, top to bottom), with tile 0 in the +top-left corner, tile 1 next to the right, and so on, e.g. +

+
0 1 2 3 +
4 5 6 7 +
+

See also tile() and setTiles(). + +

void TQCanvas::setTiles ( TQPixmap p, int h, int v, int tilewidth, int tileheight ) [virtual] +

+Sets the TQCanvas to be composed of h tiles horizontally and v tiles vertically. Each tile will be an image tilewidth by tileheight pixels from pixmap p. +

The pixmap p is a list of tiles, arranged left to right, (and +in the case of pixmaps that have multiple rows of tiles, top to +bottom), with tile 0 in the top-left corner, tile 1 next to the +right, and so on, e.g. +

+
0 1 2 3 +
4 5 6 7 +
+

If the canvas is larger than the matrix of tiles, the entire +matrix is repeated as necessary to cover the whole canvas. If it +is smaller, tiles to the right and bottom are not visible. +

The width and height of p must be a multiple of tilewidth +and tileheight. If they are not the function will do nothing. +

If you want to unset any tiling set, then just pass in a null +pixmap and 0 for h, v, tilewidth, and +tileheight. + +

void TQCanvas::setUnchanged ( const TQRect & area ) [virtual] +

+Marks area as unchanged. The area will not be redrawn in +the views for the next update(), unless it is marked or changed +again before the next call to update(). + +

void TQCanvas::setUpdatePeriod ( int ms ) [virtual] +

+Sets the canvas to call update() every ms milliseconds. Any +previous setting by setAdvancePeriod() or setUpdatePeriod() is +overridden. +

If ms is less than 0 automatic updating will be stopped. + +

TQSize TQCanvas::size () const +

+ +

Returns the size of the canvas, in pixels. + +

int TQCanvas::tile ( int x, int y ) const +

+ +

Returns the tile at position (x, y). Initially, all tiles +are 0. +

The parameters must be within range, i.e. +0 < x < tilesHorizontally() and +0 < y < tilesVertically(). +

See also setTile(). + +

int TQCanvas::tileHeight () const +

+ +

Returns the height of each tile. + +

int TQCanvas::tileWidth () const +

+ +

Returns the width of each tile. + +

int TQCanvas::tilesHorizontally () const +

+ +

Returns the number of tiles horizontally. + +

int TQCanvas::tilesVertically () const +

+ +

Returns the number of tiles vertically. + +

void TQCanvas::update () [virtual slot] +

+Repaints changed areas in all views of the canvas. +

See also advance(). + +

bool TQCanvas::validChunk ( int x, int y ) const +

+ +

Returns TRUE if the chunk position (x, y) is on the canvas; +otherwise returns FALSE. +

See also onCanvas(). + +

bool TQCanvas::validChunk ( const TQPoint & p ) const +

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

Returns TRUE if the chunk position p is on the canvas; otherwise +returns FALSE. +

See also onCanvas(). + +

int TQCanvas::width () const +

+ +

Returns the width of the canvas, in pixels. + +

Example: canvas/canvas.cpp. + +

+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