CView

Heritage

Description

Usage

Protected Data Members

Private Data Members

Friends

Public Methods

Constructor and Destructor Methods

Visibility State Methods

Activate Events

Enable/Disable Events

Mouse Events

Draw Events

Other Events

Scrolling Methods

Coordinates and Locations

Environment Methods

Glue Methods

Dragging and Stretching Methods

Utility Methods

Printing Methods

CBoss Messages and Events

"Wide Interface" Methods

Event Handler Methods

TDI Enabling Method

Protected Methods

Utility Methods

Heritage

Subclasses: CNativeTextEdit, CNativeView, CSubview, CText, CWireFrame

Description

All objects in the CView hierarchy can be enabled or disabled, meaning that they can receive events or not receive events. However, even when a view is disabled, it can still receive moving and sizing events. Setting the moving and sizing to TRUE in effect disables a view because that view no longer acts as it usually does-as a button, for example. Instead, it simply acts as an object that is being moved and sized.

One special kind of CView, the subview, has the added ability to contain other views recursively nested within it. To manage the subviews, XVT-Power++ provides different types of methods. One type, the "Do" methods, are message passing functions that propagate events to recursively nested subviews. For example, DoShow propagates the Show message, notifying each nested subview to reveal itself and to propagate the message recursively on down to its nested subviews. This capability for propagation is very important for classes derived from CSubview because subviews often need to propagate a message to all of their nested views.

CView is a more general case because it does not nest subviews. XVT-Power++ is structured so that all viewable objects have the same basic functionality, whether they are a CView or a CSubview. That is, there is a "wide interface" to CView and its derived classes. You do not need to know whether a particular view has subviews. You simply call the "Do" method, and that method propagates through all the views. If the view cannot contain subviews, then it just propagates the message to itself. Every time there is a "Do" method at the CView level, this method has been provided for a "wide interface" so that CView objects can be handled just like CSubview objects, as is often noted in the following discussion of the methods on CView.

Usage

Protected Data Members

Private Data Members

Friends

Public Methods

CView(CSubview* theEnclosure, const CRect& theRegion,
	const CStringRW& theTitle = NULLString);

A constructor. theEnclosure is a pointer to the subview that will contain the view. theRegion is a coordinate location, local to the enclosure, that is used to place the view. If a title is not passed in, then theTitle will be set to NULLString.

CView(const CView& theView);

A copy constructor, which takes another view. It takes the attributes of the view it is copying and mimics them.

CView& operator=(const CView& theView);

An assignment operator that is used for cloning a view.

virtual ~CView(void);

The destructor. It cleans up after the view is closed.

BOOLEAN IView(BOOLEAN isVisible = TRUE,
	 GLUETYPE theGlue = NULLSTICKY);

The initializer, which takes a visibility state and a glue type.

virtual BOOLEAN IsVisible(void) const;

Takes no arguments but returns a BOOLEAN value, which is TRUE if the view is visible and FALSE if the view is invisible.

virtual void Show(void);

Makes the view visible.

virtual void Hide(void);

Makes the view invisible.

virtual void DoShow(void);

Sends the view a message to become visible; the view reveals itself and in turn sends a message to its subviews to reveal themselves. DoShow is the "wide interface" counterpart of Show. At the CView level, DoShow translates to a simple Show. However, it is overridden by CSubview to implement message passing to all of the subviews.

virtual void DoHide(void);

Sends the view a message to become invisible; the view hides itself and sends a message to its subviews to hide themselves. This method is the "wide interface" counterpart of Hide.

virtual BOOLEAN IsActive(void) const;

Indicates whether the state of a view is active or inactive. It returns a BOOLEAN value of TRUE or FALSE.

virtual void Activate(void);

Sets the state of the view to active so that it is currently the view that will receive user input through keyboard or mouse events.

virtual void Deactivate(void);

Sets the state of the view to inactive, which means that it is currently not the view that will receive user input through keyboard or mouse events.

virtual void DoActivate(void);

Changes a view's state to active so that it is currently the view that will receive user input through keyboard or mouse events. The view in turn notifies its subviews to become active. In this case, the message translates as an Activate message.

virtual void DoDeactivate(void);

Changes a view's state so that it is currently not the view that will receive user input through keyboard or mouse events. The view in turn notifies its subviews to become inactive. In this case, the message translates to a Deactivate message.

virtual BOOLEAN IsEnabled(void) const;

Indicates whether a view is enabled to receive events (TRUE) or disabled (FALSE) so that it cannot receive events.

virtual void Disable(void);

Disables a view so that it cannot receive events.

virtual void Enable(void);

Enables a view so that it can receive events.

virtual void DoEnable(void);

Enables a view so that it can receive events. The view in turn notifies its subviews to become enabled. This message may be passed down until it reaches the deepest subview.

virtual void DoDisable(void);

Disables a view so that it cannot receive events. The view in turn notifies its subviews to become enabled. This message may be passed down until it reaches the deepest subview.

Mouse events are passed directly to the view at the location where the event occurs. By default, neither the Shift key nor the Control key is used in conjunction with the mouse button. The base mouse methods have an argument called theLocation, which is the location of the cursor when the mouse button was clicked. This point, theLocation, is in local coordinates, that is, coordinates relative to the view's top-left corner. Each method also has a theButton argument that specifies which mouse button is used and can have the values 0 (left), 1 (middle), or 2 (right). Typically, if you want to override the default parameters of a method for mouse events, you override the base method, not the "Do" method. For example, you would override the parameters of MouseDown rather than those of DoMouseDown.

Like the base mouse methods, the "Do" mouse methods take a parameter named theLocation. However, for the "Do" methods theLocation is in global, window-relative coordinates. The "Do" methods take the global coordinate, translate it into a local coordinate, and call the corresponding base mouse method. However, at the CSubview level, more computation is required to verify whether the global coordinate is contained in one of the subviews.

virtual void MouseDown(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user presses down a mouse button over a view containing local coordinate theLocation, the view receives and handles this event.

virtual void MouseMove(CPoint theLocation,
	short theButton	= 0, 
	BOOLEAN isShiftKey	=FALSE, 
	BOOLEAN isControlKey	=FALSE);

When the user moves the mouse over a view containing local coordinate theLocation, the view receives and handles this event, whether the mouse button is down or not.

virtual void MouseUp(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	=FALSE, 
	BOOLEAN isControlKey	=FALSE);

When the user releases a mouse button over a view containing local coordinate theLocation, the view receives and handles this event. This event is not necessarily preceded by a MouseDown or MouseMove event because those button actions may have taken place outside the view.

virtual void MouseDouble(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user double clicks a mouse button over a view containing local coordinate theLocation, the view receives and handles this event.

virtual void DoMouseDown(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey 	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user presses down a mouse button at global coordinate theLocation, the view translates this coordinate into a local coordinate and calls MouseDown.

virtual void DoMouseMove(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user moves the mouse at global coordinate theLocation, the view translates this coordinate into a local coordinate and calls MouseMove.

virtual void DoMouseUp(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user releases a mouse button at global coordinate theLocation, the view translates this coordinate into a local coordinate and calls MouseUp.

virtual void DoMouseDouble(CPoint theLocation,
	short theButton 	= 0, 
	BOOLEAN isShiftKey	= FALSE, 
	BOOLEAN isControlKey	= FALSE);

When the user double clicks the mouse at global coordinate theLocation, the view translates this coordinate into a local coordinate and calls MouseDouble.

virtual CView* FindHitView(
	const CPoint& theLocation) const;

A method that returns either a pointer to the view through which the method is invoked or a pointer to the view's wire frame in case the view has an active wire frame for moving and sizing (see CWireFrame). Whenever a view is about to receive a mouse event, FindHitView is called to find out whether the event should go to the view or to its wire frame.

virtual void Invalidate(
	const CRect& theFrame = MAXRect);

Invalidate an entire view or a sub-frame of a view. Invalidating allows the windowing system to determine regions that do not need to be drawn. For aggregate views this is generally faster than DoDraw().

virtual void Draw(const CRect& theClippingRegion);

Takes care of any drawing the view must do. theClippingRegion is the part of the view that needs to be drawn. theClippingRegion is in global, window-relative coordinates. If a CRect is passed in, the clipping region is set to the entire region that the view occupies.

virtual void DoDraw(
	const CRect& theClippingRegion = MAXRect);

The view refreshes (draws) itself and notifies each of its subviews to do the same. theClippingRegion is the part of the view that needs to be refreshed, and it is represented in global, window-relative coordinates; if it is set to MAXRect, the entire view is drawn. This method is automatically called after an E_UPDATE event. If a CRect is passed in, the clipping region is set to the entire region that the view occupies.

virtual void Key(const CKey& theKey);

Sends a keyboard event to a window. theKey represents the character key that was pressed, including whether the Shift or Control key was pressed at the same time.

virtual void DoKey(const CKey&);

Method sent to a view with focus when a keyboard event is received. This is a wide interface method which simply invokes the view's Key() method, where the actual event-handling code should be placed. DoKey() is provided with a CKey object that describes the keyboard event, including information regarding the actual key pressed as well as whether other keys pressed simultaneously (e.g., Shift, Ctl, Alt).

virtual void Size(const CRect& theNewSize);

Resets the region of the view. The reset region could be in a different location and have completely different dimensions-a

new width or a new height. The coordinates of the region, theNewSize, are relative to the enclosure-like the coordinates of the region that is passed in when a view is instantiated.

virtual void DoSize(const CRect& theNewSize);

The "wide interface" counterpart of Size.

virtual void SetFont(const CFont &theNewFont, 
	BOOLEAN isUpdate = FALSE);

Takes a font and sets the view's environment to have that font. When the font of the global environment is changed, all views sharing that environment get a SetFont message with the isUpdate parameter set to TRUE. The isUpdate parameter indicates whether this SetFont message is simply an update message or whether it is a "real" SetFont message meaning that this particular view should set its own font to the new font.

virtual void DoSetFont(const CFont &theNewFont, BOOLEAN isUpdate = FALSE);

The "wide interface" counterpart of SetFont.

virtual BOOLEAN ClassCanGetKeyFocus() const;

ClassCanGetKeyFocus() returns TRUE if the class can accept key focus: that is, a class that does something meaningful with keystrokes. For example, CText, a static text class, does not accept key focus, while NLineText, an editable text class, does accept focus.

virtual BOOLEAN CanGetKeyFocus() const;

CanGetKeyFocus() returns TRUE if an individual object can accept key focus. By default, an object can accept key focus if its class accepts key focus and if the object is visible and enabled. Thus, a disabled NLineText returns TRUE for ClassCanGetKeyFocus()(see above) but FALSE for CanGetKeyFocus().

virtual void VScroll(SCROLL_CONTROL theType,
	UNITS thePos);

A method called when a scrollbar receives a vertical scroll event.

virtual void HScroll(SCROLL_CONTROL theType,
	UNITS thePos);

A method called when a scrollbar receives a horizontal scroll event.

See Also: For a description of coordinate spaces for nested views, see "The Point of Origin" section in the "Views and Subviews" chapter of the Guide to XVT Development Solution for C++.

virtual CRect GetFrame(void) const;

Returns the region of a view in coordinates that are relative to its enclosure.

virtual CRect GetVisibleFrame(void) const;

Returns the view's visible frame in coordinates that are relative to its enclosure. In all cases except with NListButton and NListEdit, this method is the same as the GetFrame method.

virtual CRect GetGlobalFrame(void) const;

Returns the region of a view in global, or window-relative, coordinates. This method is the same as GetFrame()+GetOrigin().

virtual CRect GetClippedFrame(void) const;

Views are clipped to their enclosures, so portions of a view may not be visible. This method returns a region (CRect) with the coordinates of the visible portion of a clipped view. These coordinates are global, or window-relative. Usually, you will call GetClippedFrame before you call DoDraw in order to pass the smallest region possible to DoDraw. Because Draw and DoDraw take window-relative coordinates, GetClippedFrame returns a window-relative CRect.

virtual CRect GetLocalFrame(void) const;

Returns a frame that has a top-left corner of 0,0 and a bottom-right corner equal to the view's width and height.

virtual CPoint GetOrigin(void) const;

Returns the origin of the enclosing view in window-relative coordinates.

virtual CPoint GetGlobalOrigin(void) const;

Returns the view's origin, relative to the window.

virtual void SetOrigin(const CPoint& theDeltaPoint);

Takes the current origin of the view and adds theDeltaPoint to it. This method should not be used to move a view; to move a view, use the Size method.

virtual void DoSetOrigin(const CPoint& theDeltaPoint);

The "wide interface" counterpart of SetOrigin. This method takes the current origin of the view and adds theDeltaPoint to it, and, then, it does the same thing recursively to the view's subviews.

virtual const CEnvironment* GetEnvironment(void) const;

For purposes of consistency, conciseness, and ease of use, views often share environments-with their enclosure, their window, their document, or their application. This method tests to see if a view is using its own private environment. If not, it checks the environment of the view's enclosure. If the view's enclosure is not using an environment of its own, GetEnvironment recurses upward until it finds some environment that is being used and returns it. At the top level, the default environment of the CApplication object is always available.

virtual void SetEnvironment(const CEnvironment& theNewEnvironment, BOOLEAN isUpdate = FALSE);

Sets the environment for a view, using theNewEnvironment that is passed to it. By default, views share their enclosure's environment. However, as soon as you use SetEnvironment to give a view an environment of its own, the view uses that environment instead of the shared environment.

When the global environment is changed, all views sharing that environment get a SetEnvironment message with the isUpdate parameter set to TRUE. The isUpdate parameter indicates whether this SetEnvironment message is simply an update message or whether it is a "real" SetEnvironment message meaning that this particular view should set its own environment to the new environment.

virtual void DoSetEnvironment(const CEnvironment& theNewEnvironment, BOOLEAN isUpdate = FALSE);

Sets the environment for the view object, which notifies each of its subviews of the environment parameters of theNewEnvironment. This method is the "wide interface" counterpart of SetEnvironment.

When a view's environment is changed with DoSetEnvironment, all of its nested views get a DoSetEnvironment message with the isUpdate parameter set to TRUE. The isUpdate parameter indicates whether this DoSetEnvironment message is simply an update message or whether it is a "real" DoSetEnvironment message meaning that this particular view should set its own environment to the new environment and pass this change down to all of its child views that are sharing its environment.

virtual BOOLEAN IsEnvironmentShared(void);

A convenient method for finding out if a view is sharing an environment with another object. It returns FALSE if the view is using an environment of its own.

virtual void SetGlueObject(CGlue* theGlue, 
	BOOLEAN isDeleteOld = TRUE);

This method allows you to set the glue object for the window. If TRUE is passed to isDeleteOld, then the old glue object is deleted. Otherwise, the user must do a GetGlueObject before calling this method and is responsible for deleting the previous glue object.

virtual CGlue* GetGlueObject(void);

Returns the current glue object.

virtual GLUETYPE GetGlue(void) const;

Returns the glue type of a view.

virtual void SetGlue(GLUETYPE theGlue);

Sets the glue for a view, giving it one of the possible types of glue.

virtual void DoSetGlue(GLUETYPE theGlue);

The "wide interface" counterpart of SetGlue. It sets the glue type of the view and then recursively sets the glue of the view's subviews to that type.

virtual void Glue();

Sends a message to the view's glue object, which in turn resizes the view according to the glue settings. XVT-Power++ calls this method automatically whenever a view's coordinates may need updating because its enclosure has been resized.

Views can generate these events: WFSelectCmd, WFDeselectCMd, and WFMoveCmd, depending on whether a view is selected, deselected, or moved/sized. DoCommands can pass along data in the form of a void pointer so that view events can send along a pointer to the view object that is selected, deselected, or moved. Thus, you can trap the selection, deselection, or moving of views as these events happen by putting a case in the DoCommands.

virtual BOOLEAN IsDraggable(void) const;

Returns TRUE if the view can be dragged.

virtual void SetDragging(BOOLEAN isDraggable);

Sets the dragging of a view to TRUE so that the view can be dragged or to FALSE so that the view cannot be dragged.

virtual void DoSetDragging(BOOLEAN isDraggable);

The "wide interface" counterpart of SetDragging. It sets the dragging for the view and then recursively sets it for the view's subviews.

virtual BOOLEAN IsSizable(void) const;

Returns a BOOLEAN value of TRUE if the view can be sized.

virtual void SetSizing(BOOLEAN isSizable);

Takes a BOOLEAN value that sets the sizing of a view to TRUE so that the view can be sized or to FALSE so that the view cannot be sized.

virtual void DoSetSizing(BOOLEAN isSizable);

The "wide interface" counterpart of SetSizing. It sets the sizing for the view and then recursively sets it for the view's subviews.

virtual void SetWireFrame(CWireFrame* theNewWireFrame);

Sets a new wire frame for a view to use instead of the default one.

virtual CWireFrame* GetWireFrame(void) const;

Returns the wire frame of the view.

virtual CWindow* GetCWindow(void) const;

Returns the CWindow of the view. Every view must belong to some window, and this method returns a pointer to the window enclosure of the view.

virtual void SetCommand(long theCommand);

By default, every view generates a command when it receives a mouse click. By default, some views override this command. SetCommand allows you to set the command for the view.

virtual long GetCommand(void) const;

Returns the command generated by a view when it receives a mouse click.

virtual void SetDoubleCommand(long theCommand);

By default, every view generates a double command when it receives a double mouse click. SetDoubleCommand allows you to set the double command for the view.

virtual long GetDoubleCommand(void) const;

Returns the command generated by a view when it receives a double mouse click.

virtual void SetTitle(const CStringRW& theNewTitle);

Gives the view the title designated by theNewTitle.

virtual const CStringRW GetTitle(void) const;

Returns the view's title. If the view does not have a title, this method returns NULL.

virtual CSubview* GetEnclosure(void) const;

Returns the view's enclosure, which is a CSubview object because only CSubview objects can act as enclosures for other views.

virtual void SetEnclosure(CSubview* theEnclosure);

Sets the enclosure for the view to a different enclosure. Note that if a view belongs to a certain enclosure and then it is placed inside of a different enclosure, its location relative to the window is also going to change. theEnclosure is a CSubview object because only CSubview objects can act as enclosures for other views

virtual WINDOW GetXVTWindow(void) const;

Returns an XVT Portability Toolkit type of window handle. This method is useful if you want to manipulate the window at the XVT Portability Toolkit level.

WIN_TYPE GetXVTType(void) const;

Returns the XVT Portability Toolkit type of the native view.

virtual BOOLEAN DoPrint(const CRect& theRegion) const;

Notifies the view to print itself. The view sends itself to the printer on a separate page. theRegion specifies the part of the view that is to be drawn in coordinates relative to the enclosure. The part of the view that clips to this region is the part that is actually printed.

virtual void DoPrintDraw(const CRect& theRegion);

A method analogous to DoDraw. It goes through the view's list of subviews, notifying them to print. At the CView level, this is a "wide interface" method. At the CSubview level, there is a DoPrintDraw method that does actually go through the list of subviews and notifies them to print.

virtual void PrintDraw(const CRect& theRegion);

A method in charge of doing any drawing that should be sent to the printer. This drawing is just like the drawing done on the screen using the XVT Portability Toolkit xvt_dwin_draw_* functions. If you were to write your own printer Draw method, it would look just as if you were printing from the screen. You would still print using the view's XVT Portability Toolkit window, which can be obtained through the GetXVTWindow method. GetXVTWindow can return either a regular screen window or a printed window, depending on whether printing is being done. PrintDraw just calls the regular Draw method, and in most cases this is adequate. For some views, however, you may want to modify the way that drawing is done for the printer and not for the screen. In this case, you can override PrintDraw, putting in your own drawing specifications.

virtual const RWOrdered* GetSubObjects(void) const;

A pure virtual method that must be defined by any class derived from CBoss, specifically, CApplication, CDocument, CView, and CSubview. It returns a list of any subobjects associated with a given object. For example, the application would return a list of all its documents, a document would return a list of all its windows, a window would return a list of all its enclosed views, a subview would return a list of all its enclosed views, and so on. At the CView level, this is a "wide interface" method.

virtual void DoCommand(long theCommand, 
	void* theData=NULL);

A method part of the DoCommand chain of events, which propagates commands up the XVT-Power++ application framework event hierarchy. The void pointer theData can be used to pass any user-defined structure to the DoCommand method.

virtual CView* FindDeepSubview(const CPoint& theLocation) const;

In a nesting of views, finds the deepest subview that contains the coordinate theLocation. Since CView contains no nested subviews, this method returns NULL.

virtual CView* FindSubview(const CPoint& theLocation) const;

Finds the subview that contains the coordinate theLocation. If it does not find one-which it does not in the case of CView-it returns NULL.

virtual CView* FindSubview(long theViewId) const;

This is the "wide interface" counterpart of the FindSubview method of CSubview. CViews do not have subviews. Thus, this method always returns NULL.

virtual CView* GetSelectedView(void) const;

When a view is selected, the window containing this view returns a pointer to it. The view can thus be moved and sized by the user. Since CView contains no nested subviews, this method returns NULL.

virtual CView* FindEventTarget(const CPoint& theLocation) const;

A method called to find the target of a mouse event within a subview. This virtual method is defined to return the deepest subview at the global coordinates of theLocation. This method can be overridden by a subview in order to trap all events regardless of the subviews it contains or to change the event targeting algorithm. For example, a list box contains many subviews (text items). When you click on a text item inside a list box, the event does not go to the CText view. Instead, the list box overrides FindEventTarget and traps the event by returning this (itself) as the target for the mouse events received. Then, it treats the mouse events as necessary, without sending them on to its subviews.

virtual const RWOrdered* GetSubviews(void) const;

This is the "wide interface" counterpart of the GetSubviews method of CSubview. CViews do not have subviews. Thus, this method always returns NULL.

virtual CView* FindResourceView(long theContainerId, 
	long theId) const;

This finds a view based upon the resource container ID and the resource ID of the object. The method returns the CView*. Note that CViews do not have subviews. Thus, this method always returns NULL when called using a CView container ID.

virtual BOOLEAN HitTest(const CPoint &theLoc) const;

Determines whether the location of a point is within the current view.

virtual void DoTimer(long theTimerId);

A method called when the XVT Portability Toolkit generates a timer (E_TIMER) event. You set a timer using the XVT Portability Toolkit's xvt_timer_create function, which takes a window and a time interval (in milliseconds) and returns an ID number for the timer. This is the ID number passed to theTimerId of DoTimer. When the timer generates a timer event, CSwitchBoard passes it to the XVT Portability Toolkit-designated window via DoTimer. The window passes it on to its selected view, if it has one. The timer event may propagate upwards from a view to the window to the document and all the way to the application object, stopping at any point.

virtual void DoUser(long theUserId, void* theData);

A method called when the XVT Portability Toolkit generates a user (E_USER) event. As noted in the XVT Portability Toolkit Guide, user events allow you to pass custom events to windows and dialogs. theUserId is the ID number that designates a particular kind of user event. The void pointer theData can be used to pass any user-defined structure to DoUser, just as you would for a DoCommand. As with timer events, CSwitchBoard passes a user event to a designated window. The window passes it on to its selected view, if it has one. The timer event may propagate upwards from a view to the window to the document and all the way to the application object, stopping at any point.

virtual void DoUpdateModel(
	long theControllerId, 
	long theCommand, 
	const CModel* theModel);

DoUpdateModel() supports TDI messages applicable to view classes. These messages act on the view title and include
• TDIClearCmd (clear title)
• TDIReplaceCmd (replace title)
• TDIAppendCmd (append to title)

virtual BOOLEAN Prepare(const CRect& theClippingRegion);

Prepares the view for drawing, basically by setting its clipping region. If the view object needs to be redrawn, this method returns TRUE; it returns FALSE otherwise.

void BuildView(CSubview* theEnclosure, 
	const CRect& theRegion);

A method called during construction and equal operations. It takes care of building the view.

void CopyView(const CView& theView);

A method called during construction and equal operations. It takes care of copying the view.