Contents Up Previous Next

wxCanvas: wxWindow

A canvas is a subwindow onto which graphics and text can be drawn, and mouse and keyboard input can be intercepted. At present, panel items cannot be placed on a canvas.

To determine whether a canvas is colour or monochrome, test the canvas's device context Colour boolean member variable.

When you draw onto a canvas, you are really drawing onto a device context (see wxDC, wxCanvasDC). Although you can use the members of wxCanvas for drawing, it is much better to get the device context from the canvas (see GetDC) and draw into that. Then, code which can draw into one device context can be reused for others, such as PostScript or memory device contexts (see wxPostScriptDC and wxMemoryDC).

wxCanvas::wxCanvas
wxCanvas::~wxCanvas
wxCanvas::AllowDoubleClick
wxCanvas::BeginDrawing
wxCanvas::Clear
wxCanvas::Create
wxCanvas::CrossHair
wxCanvas::DestroyClippingRegion
wxCanvas::DrawArc
wxCanvas::DrawEllipse
wxCanvas::DrawLine
wxCanvas::DrawLines
wxCanvas::DrawPolygon
wxCanvas::DrawPoint
wxCanvas::DrawRectangle
wxCanvas::DrawRoundedRectangle
wxCanvas::DrawSpline
wxCanvas::DrawText
wxCanvas::EnableScrolling
wxCanvas::EndDrawing
wxCanvas::FloodFill
wxCanvas::GetDC
wxCanvas::GetScrollPage
wxCanvas::GetScrollPixelsPerUnit
wxCanvas::GetScrollPos
wxCanvas::GetScrollRange
wxCanvas::GetScrollUnitsPerPage
wxCanvas::GetVirtualSize
wxCanvas::IntDrawLine
wxCanvas::IntDrawLines
wxCanvas::IsRetained
wxCanvas::OnChar
wxCanvas::OnEvent
wxCanvas::OnPaint
wxCanvas::OnScroll
wxCanvas::Scroll
wxCanvas::SetBackground
wxCanvas::SetClippingRegion
wxCanvas::SetBrush
wxCanvas::SetFont
wxCanvas::SetLogicalFunction
wxCanvas::SetPen
wxCanvas::SetScrollbars
wxCanvas::SetScrollPage
wxCanvas::SetScrollPos
wxCanvas::SetScrollRange
wxCanvas::SetTextBackground
wxCanvas::SetTextForeground
wxCanvas::ViewStart
wxCanvas::WarpPointer


wxCanvas::wxCanvas

void wxCanvas(wxWindow *parent, int x = -1, int y = -1,
int width = -1, int height = -1,
long style = wxRETAINED, char *name = "canvas")

Constructor.

Under Windows and Motif, the parent can be either a frame or panel. Under XView, the parent must be a frame.

The parameters x, y, width and height can be omitted on construction if the position and size will later be set (for example by a application frame's OnSize callback, or if there is only one subwindow for the frame, in which case the subwindow fills the frame).

The style parameter may be a combination (using the C++ bitwise 'or' operator) of the following flags:

wxBORDER Gives the canvas a thin border (MS Windows and Motif only).
wxRETAINED Gives the canvas a wxWindows-implemented backing store, making repainting much faster but at a potentially costly memory premium (XView and Motif only).

The name parameter is used to associate a name with the canvas, allowing the application user to set Motif resources for individual canvases.


wxCanvas::~wxCanvas

void ~wxCanvas(void)

Destructor.


wxCanvas::AllowDoubleClick

void AllowDoubleClick(int interval)

Allows or disables double click handling on a canvas (Motif, MS Windows). Specify a double-click interval in milliseconds.

See also wxMouseEvent::ButtonDClick.


wxCanvas::BeginDrawing

void BeginDrawing(void)

Allows optimization of drawing code under MS Windows. Enclose drawing primitives between BeginDrawing and EndDrawing calls.


wxCanvas::Clear

void Clear(void)

Clears the canvas (fills it with the current background brush).


wxCanvas::Create

void Create(wxWindow *parent, int x = -1, int y = -1,
int width = -1, int height = -1,
long style = wxRETAINED, char *name)

Creates the canvas for two-step construction. Derived classes should call or replace this function. See wxCanvas::wxCanvas for details.


wxCanvas::CrossHair

void CrossHair(float x, float y)

Displays a cross hair using the current pen. This is a vertical and horizontal line the height and width of the canvas, centred on the given point.


wxCanvas::DestroyClippingRegion

void DestroyClippingRegion(void)

Destroys the current clipping region so that none of the canvas is clipped.


wxCanvas::DrawArc

void DrawArc(float x1, float y1, float x2, float y2, floatxc, floatyc)

Draws an arc, centred on (xc, yc), with starting point (x1, y1) and ending at (x2, y2). The current pen is used for the outline and the current brush for filling the shape.


wxCanvas::DrawEllipse

void DrawEllipse(float x, float y, float width, float height)

Draws an ellipse contained in the rectangle with the given top left corner, and with the given size. The current pen is used for the outline and the current brush for filling the shape.


wxCanvas::DrawLine

void DrawLine(float x1, float y1, float x2, float y2)

Draws a line from the first point to the second. The current pen is used for drawing the line.


wxCanvas::DrawLines

void DrawLines(int n, wxPoint points[], float xoffset = 0, float yoffset = 0)

void DrawLines(wxList *points, float xoffset = 0, float yoffset = 0)

Draw lines using an array of points of size n, or list of pointers to points, adding the optional offset coordinate. The current pen is used for drawing the lines. The programmer is responsible for deleting the list of points.


wxCanvas::DrawPolygon

void DrawPolygon(int n, wxPoint points[], float xoffset = 0, float yoffset = 0,
int fill_style = wxODDEVEN_RULE)

void DrawPolygon(wxList *points, float xoffset = 0, float yoffset = 0, int fill_style = wxODDEVEN_RULE)

Draw a filled polygon using an array of points of size n, or list of pointers to points, adding the optional offset coordinate.

The last argument specifies the fill rule: wxODDEVEN_RULE (the default) or wxWINDING_RULE.

The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. The programmer is responsible for deleting the list of points.

Note that wxWindows automatically closes the first and last points.


wxCanvas::DrawPoint

void DrawPoint(float x, float y)

Draws a point using the current pen.


wxCanvas::DrawRectangle

void DrawRectangle(float x, float y, float width, float height)

Draws a rectangle with the given top left corner, and with the given size. The current pen is used for the outline and the current brush for filling the shape.


wxCanvas::DrawRoundedRectangle

void DrawRoundedRectangle(float x, float y, float width, float height, float radius = 20)

Draws a rectangle with the given top left corner, and with the given size. The corners are quarter-circles using the given radius. The current pen is used for the outline and the current brush for filling the shape.

If radius is positive, the value is assumed to be the radius of the rounded corner. If radius is negative, the absolute value is assumed to be the proportion of the smallest dimension of the rectangle. This means that the corner can be a sensible size relative to the size of the rectangle, and also avoids the strange effects X produces when the corners are too big for the rectangle.


wxCanvas::DrawSpline

void DrawSpline(wxList *points)

Draws a spline between all given control points, using the current pen. Doesn't delete the wxList and contents. The spline is drawn using a series of lines, using an algorithm taken from the X drawing program 'XFIG'.

void DrawSpline(float x1, float y1, float x2, float y2, float x3, float y3)

Draws a three-point spline using the current pen.


wxCanvas::DrawText

void DrawText(char *text, float x, float y)

Draws a text string at the specified point, using the current text font, and the current text foreground and background colours.


wxCanvas::EnableScrolling

void EnableScrolling(Bool xScrolling, Bool yScrolling)

Enable or disable Windows scrolling in the given direction, where in this context scrolling is the physical transfer of bits up or down the screen when a scroll event occurs. If the application scrolls by a variable amount (e.g. if there are different font sizes) then physical scrolling messes up the display.


wxCanvas::EndDrawing

void EndDrawing(void)

Allows optimization of drawing code under MS Windows. Enclose drawing primitives between BeginDrawing and EndDrawing calls.


wxCanvas::FloodFill

void FloodFill(float x, float y, wxColour *colour, int style=wxFLOOD_SURFACE)

Flood fills the canvas starting from the given point, in the given colour, and using a style:

Note: this function is available in MS Windows only.


wxCanvas::GetDC

wxCanvasDC * GetDC(void)

Get a pointer to the canvas's device context. See wxDC and wxCanvasDC.


wxCanvas::GetScrollPage

int GetScrollPage(int orient)

Returns the lines per page of the scrollbar. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose lines per page value is to be returned.


wxCanvas::GetScrollPixelsPerUnit

void GetScrollPixelsPerUnit(int *x_unit, int *y_unit)

Get the number of pixels per scroll unit (line), in each direction, as set by wxCanvas::SetScrollbars. A value of zero indicates no scrolling in that direction.


wxCanvas::GetScrollPos

int GetScrollPos(int orient)

Returns position (in scroll units) of a scrollbar. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose position is to be returned.


wxCanvas::GetScrollRange

int GetScrollRange(int orient)

Returns the maximum position of the scrollbar, in scroll units. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose range is to be returned.


wxCanvas::GetScrollUnitsPerPage

void GetScrollUnitsPerPage(int *x_page, int *y_page)

Get the number of units per page, in each direction, as set by wxCanvas::SetScrollbars. A value of zero indicates no scrolling in that direction.


wxCanvas::GetVirtualSize

w

void GetVirtualSize(int *x, int *y)

Gets the size in device units of the scrollable canvas area (as opposed to the client size, which is the area of the canvas currently visible).

Use wxDC::DeviceToLogicalX and wxDC::DeviceToLogicalY to translate these units to logical units.


wxCanvas::IntDrawLine

void IntDrawLine(int x1, int y1, int x2, int y2)

Draws a line from the first point to the second. The current pen is used for drawing the line.


wxCanvas::IntDrawLines

void IntDrawLines(int n, wxIntPoint points[], int xoffset = 0, int yoffset = 0)

Draw lines using an array of points of size n. The current pen is used for drawing the lines. The programmer is responsible for deleting the list of points.


wxCanvas::IsRetained

Bool IsRetained(void)

TRUE if the canvas has a backing bitmap.


wxCanvas::OnChar

void OnChar(wxKeyEvent& event)

This default handler interprets cursor key movement and scrolls the canvas accordingly. Override the function to change this behaviour.

The member keyCode contains the key pressed.

See wxEvtHandler::OnChar for more details.


wxCanvas::OnEvent

void OnEvent(wxMouseEvent& event)

Sent to the canvas when the user has initiated an event with the mouse. Derive your own class to handle this message. See wxCanvas::OnChar for character events, and also wxMouseEvent for how to access event information.


wxCanvas::OnPaint

void OnPaint(void)

Sent to the canvas when the canvas must be refreshed. Derive your own class to handle this message.

You can optimize painting by retrieving the rectangles that have been damaged and only repainting these. The rectangles are in terms of the client area, and are unscrolled, so you will need to do some calculations using the current view position to obtain logical, scrolled units.

Here is an example of using the wxUpdateIterator class:

// Called when canvas needs to be repainted.
void MyCanvas::OnPaint(void)
{
  // Speeds up drawing under Windows.
  GetDC()->BeginDrawing();
  wxCanvasDC *canvdc = GetDC();

  // Find Out where the window is scrolled to
  int vbX,vbY;                     // Top left corner of client
  ViewStart(&vbX,&vbY);

  int vX,vY,vW,vH;                 // Dimensions of client area in pixels
  wxUpdateIterator	upd(this); // get the update rect list

  while (upd)
  {
    vX = upd.GetX();
    vY = upd.GetY();
    vW = upd.GetWidth();
    vH = upd.GetHeight();

    // Alternatively we can do this:
    // wxRectangle rect;
    // upd.GetRect(&rect);

    // Repaint this rectangle
    <some code>

    upd ++ ;
  }
  GetDC()->EndDrawing();
}

wxCanvas::OnScroll

void OnScroll(wxCommandEvent& event)

Override this function to intercept scroll events. This member function implements the default scroll behaviour. If you do not call the default function, you will have to manage all scrolling behaviour including drawing the canvas contents at an appropriate position relative to the scrollbar.

The commandInt member of wxCommandEvent is the position of the scrollbar. The macro WXSCROLLPOS(event) may be used to access or set this member.

The extraLong member of wxCommandEvent is wxHORIZONTAL or wxVERTICAL. The macro WXSCROLLORIENT(event) may be used to access or set this member.

The eventType member of wxCommandEvent will be one of:

wxEVENT_TYPE_SCROLL_LINEDOWN Called when the scrollbar is incremented by a line, by clicking on the bottom arrow of a vertical scrollbar or right-hand arrow of a horizontal scrollbar.
wxEVENT_TYPE_SCROLL_LINEUP Called when the scrollbar is decremented by a line, by clicking on the top arrow of a vertical scrollbar or left-hand arrow of a horizontal scrollbar.
wxEVENT_TYPE_SCROLL_PAGEDOWN Called when the scrollbar is incremented by a page.
wxEVENT_TYPE_SCROLL_PAGEUP Called when the scrollbar is decremented by a page.
wxEVENT_TYPE_SCROLL_TOP Called when the scrollbar is set to the top.
wxEVENT_TYPE_SCROLL_BOTTOM Called when the scrollbar is set to the bottom.
wxEVENT_TYPE_SCROLL_THUMBTRACK Called when the the scrollbar is being dragged.

Note that not all these messages will be received on a given platform. For example, under XView, only the thumbtrack event is ever generated, and so unless the application keeps track of where the scrollbar was previously, some scrolling optimisations are not possible.

Under Windows and Motif, all messages may be generated.


wxCanvas::Scroll

void Scroll(int x_pos, int y_pos)

Scrolls a canvas so the view start is at the given point. The positions are in scroll units, not pixels, so to convert to pixels you will have to multiply by the number of pixels per scroll increment. If either parameter is -1, that position will be ignored (no change in that direction).

See also wxCanvas::SetScrollbars.


wxCanvas::SetBackground

void SetBackground(wxBrush *brush)

Sets the current background brush for the canvas, used for the pixels between dotted or dashed lines. The brush should not be deleted while being used by a canvas. All brushes are deleted automatically when the application terminates.

See also wxBrush.


wxCanvas::SetClippingRegion

void SetClippingRegion(float x, float y, float width, float height)

Sets the clipping region for the canvas. The clipping region is a rectangular area to which drawing is restricted. Possible uses for the clipping region are for clipping text or for speeding up canvas redraws when only a known area of the screen is damaged.

See also wxCanvas::DestroyClippingRegion.


wxCanvas::SetBrush

void SetBrush(wxBrush *brush)

Sets the current brush for the canvas. The brush is not copied, so you should not delete the brush unless the canvas pen has been set to another brush, or to NULL. Note that all pens and brushes are automatically deleted when the program is exited.

See also wxBrush.


wxCanvas::SetFont

void SetFont(wxFont *font)

Sets the current font for the canvas. The font is not copied, so you should not delete the font unless the canvas pen has been set to another font, or to NULL.

See also wxFont, wxCanvas::DrawText.


wxCanvas::SetLogicalFunction

void SetLogicalFunction(int function)

Sets the current logical function for the canvas. This determines how a source pixel (from a pen or brush colour, or source device context if using wxDC::Blit) combines with a destination pixel in the current device context.

The possible values and their meaning in terms of source and destination pixel values are as follows:

wxAND                 src AND dst
wxAND_INVERT          (NOT src) AND dst
wxAND_REVERSE         src AND (NOT dst)
wxCLEAR               0
wxCOPY                src
wxEQUIV               (NOT src) XOR dst
wxINVERT              NOT dst
wxNAND                (NOT src) OR (NOT dst)
wxNOR                 (NOT src) AND (NOT dst)
wxNO_OP               dst
wxOR                  src OR dst
wxOR_INVERT           (NOT src) OR dst
wxOR_REVERSE          src OR (NOT dst)
wxSET                 1
wxSRC_INVERT          NOT src
wxSRC_AND             AND src (MS Windows Blit only: equivalent to SRCAND)
wxSRC_OR              OR src (MS Windows Blit only: equivalent to SRCPAINT)
wxXOR                 src XOR dst
The default is wxCOPY, which simply draws with the current colour. The others combine the current colour and the background using a logical operation. wxXOR is commonly used for drawing rubber bands or moving outlines, since drawing twice reverts to the original colour.


wxCanvas::SetPen

void SetPen(wxPen *pen)

Sets the current pen for the canvas. The pen is not copied, so you should not delete the pen unless the canvas pen has been set to another pen, or to NULL. Note that all pens and brushes are automatically deleted when the program is exited.

See also wxPen.


wxCanvas::SetScrollbars

void SetScrollbars(int horiz_pixels, int vert_pixels, int x_length, int y_length,
int x_page, int y_page, int x_pos = 0, int y_pos = 0)

Sets up vertical and/or horizontal scrollbars. The first pair of parameters give the number of pixels per 'scroll step', i.e. amount moved when the up or down scroll arrows are pressed. The second pair gives the length of scrollbar in scroll steps, which effectively sets the size of the 'virtual canvas'. The third pair gives the number of scroll steps in a 'page', i.e. amount moved when pressing above or below the scrollbar control, or using page up/page down.

x_pos and y_pos optionally specify a position to scroll to immediately.

Either x_length y_length can be zero to specify no scrollbar.

For example, the following gives a canvas horizontal and vertical scrollbars with 20 pixels per scroll step, a size of 50 steps (1000 pixels) in each direction, and 4 steps (80 pixels) to a page.

canvas->SetScrollbars(20, 20, 50, 50, 4, 4);
See also wxCanvas::EnableScrolling, wxCanvas::GetScrollUnitsPerPage, wxCanvas::GetVirtualSize.


wxCanvas::SetScrollPage

void SetScrollPage(int orient, int page)

Sets the lines per page for a scrollbar. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose lines per page is to be set.


wxCanvas::SetScrollPos

void SetScrollPos(int orient, int pos)

Sets the position (in scroll units) of a scrollbar. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose position is to be set.


wxCanvas::SetScrollRange

void SetScrollRange(int orient, int range)

Sets the maximum position (in scroll units) of a scrollbar. Pass wxHORIZONTAL or wxVERTICAL to indicate the scrollbar whose range is to be set.


wxCanvas::SetTextBackground

void SetTextBackground(wxColour *colour)

Sets the current text background colour for the canvas. The colour is copied by this function. See also wxCanvas::SetTextForeground.


wxCanvas::SetTextForeground

void SetTextForeground(wxColour *colour)

Sets the current text foreground colour for the canvas. The colour is copied by this function. See also wxCanvas::SetTextBackground.


wxCanvas::ViewStart

void ViewStart(int *x, int * y)

Get the position at which the visible portion of the canvas starts. If either of the scrollbars is not at the home position, x and/or y will be greater than zero. Combined with wxWindow::GetClientSize, the application can use this function to efficiently redraw only the visible portion of the canvas. The positions are in logical scroll units, not pixels, so to convert to pixels you will have to multiply by the number of pixels per scroll increment.

See also wxCanvas::SetScrollbars.


wxCanvas::WarpPointer

void WarpPointer(int x, int y)

Moves the pointer to the given position on the canvas.