vCanvasPane
A base class to build graphical and text canvas panes.
Synopsis
- Header:
- <v/vcanvas.h>
- Class name:
- vCanvasPane
- Hierarchy:
- vPane ->vCanvasPane
Description
This is the base drawing class. You use it to build more complicated
drawing canvases, either for graphical drawing or text drawing.
The vCanvasPane class has all the basic methods needed to
interact with the drawing canvas. It does not, however, know
how to handle repainting the screen on Redraw or Resize
events. It provides utility methods for drawing on the canvas,
and several other methods that are normally overridden by your
application.
See the section vPane for a general description of panes.
Utility Methods
The following methods provide useful service without modification. Sometimes
you will want to override some of these, but you will then usually
call these methods from your derived class.
Drawing
The vCanvasPane normally creates a vCanvasPaneDC to
use for drawing, and class provides direct support by including
direct calls for the drawing methods described in the vDC
section. If your drawing will only be to the screen, then you
can use the methods of the vCanvasPane class directly.
Each of these methods is really an inline function that expands
to _cpDC->DrawWhatever().
If your drawing code might want to draw to both a screen and
a printer, you might want to use a parameter to the appropriate
drawing canvas. You can get the vDC used by the vCanvasPane
by calling GetDC().
virtual void CreateDC(void)
This method is called when the vCanvasPane is initialized.
The default is to create a drawing canvas using _cpDC = new
vCanvasPaneDC(this);. If you want to derive a different canvas
pane class from vCanvasPane perhaps using a more
sophisticated drawing canvas derived from the vCanvasPaneDC
class, you can override the CreateDC method and set the
protected vDC* _cpDC pointer to an instance of your new
drawing canvas (e.g., _cpDC = new myCanvasPaneDC(this)
instead.
vDC* GetDC()
Returns a pointer to the vDC of the current drawing canvas. The
vDC can be used for most of the drawing methods to achieve
drawing canvas independence. If your code draws via a vDC pointer,
then the same code can draw to the screen canvas or the printer canvas
depending on what the vDC points to.
VCursor GetCursor()
Returns the id of the current cursor being used in the canvas.
See SetCursor.
virtual int GetHeight()
Returns the height of the current drawing canvas in pixels.
virtual int GetHScroll(int& Shown, int& Top)
Get the status of the Horizontal Scroll bar. Returns 1 if the
scroll bar is displayed, 0 if not. Returns in Shown and
Top the current values of the scroll bar. See SetVScroll
for a description of the meanings of parameters.
virtual int GetVScroll(int& Shown, int& Top)
Get the status of the Vertical Scroll bar. See
GetHScroll for details.
virtual int GetWidth()
Returns the width of the current drawing canvas in pixels.
This is either the initial size of the window, or the size
after the user has resized the window.
void SetCursor(VCursor id)
This method sets the cursor displayed while the mouse in
in the current canvas area. The default cursor is the
standard arrow cursor used on most host platforms. You
can change the cursor displayed within the canvas area
only by calling this method.
The cursors currently supported include:
- VC_Arrow
- The standard arrow cursor.
- VC_CenterArrow
- An upward point arrow.
- VC_CrossHair
- A cross hair cursor.
- VC_EWArrows
- Double ended horizontal arrows (EastWest).
- VC_Hand
- A hand with a pointing finger (NOT ON WINDOWS).
- VC_IBar
- An I bar cursor.
- VC_Icon
- A cursor representing an icon.
- VC_NSArrows
- Double ended vertical arrows (NorthSouth).
- VC_Pencil
- A pencil (NOT ON WINDOWS).
- VC_Question
- A question mark cursor (NOT ON WINDOWS).
- VC_Sizer
- The cursor used for sizing windows.
- VC_Wait
- A cursor that symbolizes waiting, usually an hour glass.
- VC_X
- An X shaped cursor (NOT ON WINDOWS).
void SetWidthHeight(int width, int height)
This will set the size of the drawing canvas to height
and width in pixels. It will also cause a Resize
event message to be sent to the window.
virtual void SetHScroll(int Shown, int Top)
Set the horizontal scroll bar. See SetVScroll for
a description of the parameters.
virtual void SetVScroll(int Shown, int Top)
Set the vertical scroll bar. The Shown parameter
is a value from 0 to 100, and represents the percent
of the scroll bar shows of the view in the canvas. For
example, the canvas might be displaying text from a file.
If the file was 100 lines long, and the window could show
20 lines, then the value of Shown would be 20,
meaning that the canvas is showing 20 percent of the file.
As the size of the data viewed in the canvas changes, your
program should change the scroll bar to corresponding values.
The Top parameter represents where the top of
the scroll indicator should be placed. For example,
if the first line displayed in the canvas of a 100 line file
was line 40, then Top should be 40, representing
40 percent.
This model of a scroll bar can be mapped to all the underlying
windowing systems supported by
V, but the visual appearance
of the scroll bar will vary.
virtual void ShowHScroll(int OnOrOff)
virtual void ShowVScroll(int OnOrOff)
When a canvas is first displayed, it will begin with both
horizontal and scroll bars not shown by default. ShowHScroll
and ShowVScroll can be used to selectively turn on and off
the canvas scroll bars. When a scroll bar is turned off or on, the size
of the canvas may changes, so you should also call Resize after
you have set the scroll bars.
You must not call either of these methods until the canvas has
actually been instantiated on the screen. This means if your
application needs to start with scroll bars, you should have
the calls to ShowVScroll and ShowHScroll in
the code of your vCmdWindow class constructor
(or other initialization code)
after calling
vWindow::ShowWindow in your class constructor.
Platform Dependent
If you simply must access the native window for low level
drawing, V provides a couple of platform dependent
functions that can sometimes help. Be warned that your code
will then be platform dependent.
Methods for MS-Windows
HWND DrawingWindow()
This returns the HWND of the drawing window of
the current canvas. This is then used to get a DC
as needed. For example:
....
// Assume mycanvas is a pointer to your canvas pane.
// Call DrawingWindow to get the HWND used by canvas
HWND drawingWindow = mycanvas->DrawingWindow();
// Now use that HWND to call the native Windows GetDC to get a DC
HDC myHDC = ::GetDC(drawingWindow);
// use myHDC to do drawing....
// note that you will need to use native Windows drawing calls here,
// and not use V drawing functions. You can use V stuff IF you
// first release the DC, call the V code, and then get your
// own DC again. But since you are really using the DC in a native
// way, why use V at all for the drawing part at this point?
// The V GUI stuff will still work fine.
.... // your drawing code here
// IMPORTANT! When done drawing, youj must release the DC
::ReleaseDC(drawingWindow, myHDC);
Methods for X
Widget DrawingWindow()
This returns the X Widget used by the canvas.
Drawable GetXDrawable()
This returns the X Drawable used by the canvas.
Methods to Override
virtual void FontChanged(int vf)
Called when the font is changed. This usually means your
application needs to resize the window and recalculate
the number of rows and columns of text that can be displayed.
virtual void HPage(int Shown, int Top)
When the user moves the horizontal scroll bar, it generates an
HPage event. It is up to your program to intercept (override)
this method, and provide proper interpretation. This event usually
is used for large movements. The meaning of Shown and
Top represent the state of the scroll bar as set by
the user. It is then up to your program to display the
correct portion of the data shown in the canvas to correspond
to these values. Your program uses SetHScroll to
set appropriate values, and they are explained there.
The Shown value supplied here
will correspond to the value you program set for the scroll bar.
The Top value should indicate the meaningful change as input
by the user.
virtual void HScroll(int step)
This method is called when the user enters a single step command
to the scroll bar. The value of step will be positive for right or
negative for left scroll. These scrolls
are usually interpreted as discreet steps - either a line or
screenful at a time. It is up to your application to give
an appropriate interpretation.
virtual void MouseDown(int x, int y, int button)
This is called when the user clicks a button on the mouse. The
x and y indicates the position of the mouse in the
canvas when the button was clicked. Mouse events in vCanvasPane
are no-ops, and your subclass of vCanvasPane will need to
handle proper interpretation of mouse clicks.
Sorry, but thanks to the Macintosh, handling of buttons is a bit
nonportable. The button parameter will have a value of 1,
2, or 3. On X based systems, 1 is the left button, 2 is the
middle button, and 3 is the right button. On Windows, 1 is the
left button, and 3 is the right button. Thus, applications using
the left and right buttons are portable from X to Windows. The
single Macintosh button will return a value of 1.
If you intend your applications to port to all three platforms,
you will have to account for the single Macintosh button. If you
ignore X's middle button, then your applications can be directly
portable from X to Windows.
virtual void MouseMotion(int x, int y)
This is called when the mouse moves while a button is
not
pressed, and gives the current x and y of the
mouse. Most applications will ignore this information.
virtual void MouseMove(int x, int y, int button)
This is called when the mouse moves while a button is pressed,
and gives the new x, y, and button of the
mouse. Mouse events in vCanvasPane are no-ops, and your subclass
needs to interpret them.
Note that scaling applies to output only. The mouse
events will provide unscaled coordinates, and it is up
to your code to scale mouse coordinates appropriately.
Mouse coordinate
do have the translation added.
virtual void MouseUp(int x, int y, int button)
This is called when the user releases the mouse button, and
gives the final location of the mouse.
Mouse events in vCanvasPane are no-ops, and your subclass
needs to interpret them.
virtual void Redraw(int x, int y, int width, int height)
Redraw is called when the canvas needs to be redrawn.
The first redraw is generated when the canvas is first created.
Other redraws are generated when the canvas is covered or uncovered
by another window, and means the contents of the canvas must
be repainted. The vCanvasPane does not know how to repaint
the contents of the canvas, so you must override this method to
be able to keep the canvas painted.
The parameters of Redraw represent the rectangular area
that needs to be repainted. This areas is not always the whole
canvas, and it is possible that many Redraw events will
be generated in a row as the user drags a covering window off
the canvas.
The default Redraw in vCanvasPane is a
no-op, and your subclass needs to override Redraw.
virtual void Resize(int newW, int newH)
A Resize event is generated when the user changes the
size of the canvas using the resize window command provided
by the host windowing system.
The default Resize in vBaseGLCanvasPane is a
no-op, and your subclass needs to override Redraw.
virtual void VPage(int Shown, int Top)
See HPage.
virtual void VScroll(int step)
This method is called when the user enters a single step command
to the vertical scroll bar. The value of step will be
positive for down or negative for up scroll. These scrolls are
usually interpreted as discreet steps - either a line or
screenful at a time. It is up to your application to give an
appropriate interpretation.
See Also
vTextCanvasPane