LView is a PowerPlant class that is the basis for the visual hierarchy. An LView object is a pane that can contain other panes.
Methods :
The methods in this class are:
Data Members:
The data members in this class are:
Operation:
LView objects contain the panes that you draw. In other words, LView is a container object, with the panes being the contents. Objects that derive from LView are usually places where you draw things.
To learn more about views, refer to The PowerPlant Book.
Source files:
Ancestors:
Purpose:
The constructors create objects from the passed-in parameters.
Access:
Prototype:
LView();
LView( const LView &inOriginal );
LView( const SPaneInfo &inPaneInfo,
const SViewInfo &inViewInfo );
LView( LStream *inStream );Parameters:
The parameters for the constructors are:
Purpose:
The destructor destroys the object.
Access:
Prototype:
virtual ~LView();
Purpose:
Activate a View. This is an override of Activate() in LPane.
Purpose:
Adjust view when its SuperView changes identity or size. This is an override of AdaptToNewSurroundings() in LPane.
Purpose:
Adjust state of View when size of SuperView's Frame changes by the specified amounts. This is an override of AdaptToSuperFrameSize() in LPane.
Purpose:
You should not normally call this function. Call LPane::PutInside() to associate a Pane with a SuperView.
Access:
Prototype:
virtual void AddSubPane( LPane *inSub );Parameters:
The parameter for this method is:
Return:
Purpose:
Wrapper function for setting the cursor shape. View needs to determine which subpane, if any, should set the cursor shape. This is an override of AdjustCursor() in LPane.
Purpose:
Scroll the image if the specified point is outside the View's Frame.
Call this function while tracking the mouse to scroll a View in the direction of the mouse location.
Access:
Prototype:
virtual Boolean AutoScrollImage( Point inLocalPt );Parameters:
The parameter for this method is:
Return:
Returns true if the View actually scrolled, else false.
Purpose:
Calculate the coordinate origin for the Port needed to set up the local coordinates of a View.
Access:
Prototype:
virtual void CalcPortOrigin();Parameters:
Return:
Remarks:
The Port origin must be in 16-bit space. In fact, the limitation is more restrictive because the entire Port must be in 16-bit space. The origin is the top left corner. To make sure that the bottom right corner is in 16-bit space, we force the origin to be less than 2^14 (16,384), which allows Port dimensions of a maximum of 16,384 pixels. At 72 dpi, this is about 227 inches or 19 feet (much more screen or printer area than you can get with current technology).
This means that Local and Image coordinates will be the same when the Image size is less than 16,384 pixels. For Images greater than this, you can't use absolute coordinates for drawing. You need to offset the coordinates using ImageToLocalPoint() and LocalToImagePoint().
The true coordinates offset is the distance between the top left corners of the Image and the Port. If this offset is greater than 2^14, we use an effective offset that is the true offset modulo 2^14:
effective_offset = true_offset modulo 2^14
Using this effective offset maintains the bit-wise alignment of
the Port with respect to base-2 byte boundaries. This is important
for drawing Toolbox Patterns and PixPats, as well as for CopyBits() calls.
Purpose:
Calculate the portion of the Frame which is revealed through the frames of all SuperViews. mRevealedRect is in Port coordinates.
Access:
Prototype:
void CalcRevealedRect();Parameters:
Return:
Purpose:
Handle a click inside a View. This is an override of Click() in LPane.
Purpose:
Return the number of horizontal and vertical Panels. A Panel is a "frameful" of a View's Image. This is an override of CountPanels() in LPane.
Purpose:
Deactivate a View. This is an override of Deactivate() in LPane.
Purpose:
Deletes all subpanes of a View.
Access:
Prototype:
void DeleteAllSubPanes();Parameters:
Return:
Purpose:
Disable a View. This is an override of Disable() in LPane.
Purpose:
Validate the area occupied by a View. This removes the View area from the update region so that the View won't be redrawn during the next Update event.
This is an override of DontRefresh() in LPane.
Purpose:
Draw a View and all its subpanes. This is an override of Draw() in LPane.
Purpose:
Enable a View. This is an override of Enable() in LPane.
Purpose:
Access:
Prototype:
virtual Boolean EstablishPort();Parameters:
Return:
Return true if the port was set successfully, else false.
Purpose:
Adjust the size and location of a SubPane to fit within the interior of a View in the horizontal and/or vertical directions.
Access:
Prototype:
virtual void ExpandSubPane( LPane *inSub,Parameters:
Boolean inExpandHoriz,
Boolean inExpandVert);
The parameters for this method are:
Return:
Purpose:
Find the Pane of a View which has the specified ID. This is an override of FindConstPaneByID() in LPane.
Purpose:
Return the most deeply nested visible SubPane which contains the specified point, which is in Port coordinates. This is an override of FindDeepSubPaneContaining() in LPane.
Purpose:
Find the Pane of a View which has the specified ID. This is an override of FindPaneByID() in LPane.
FindShallowSubPaneContaining()
Purpose:
Return the immediate visible SubPane which contains the specified point, which is in Port coordinates. This is an override of FindShallowSubPaneContaining() in LPane.
Purpose:
Find the SubPane of this View that is hit by the specified point. This is an override of FindSubPaneHitBy() in LPane.
Purpose:
Wrapper function for FinishCreateSelf. This is an override of FinishCreate() in LPane.
You will rarely want to override this function.
Purpose:
Prepare for drawing in the View by setting the Port and clipping area. This is an override of FocusDraw() in LPane.
Purpose:
Prepare for drawing in the View by setting the Port and clipping area. This is an override of FocusExposed() in LPane.
Purpose:
Get the Descriptor of the Pane of a View which has the specified ID. The Pane may be the View itself, or a subpane of the View.
Access:
Prototype:
virtual StringPtr GetDescriptorForPaneID(Parameters:
PaneIDT inPaneID,
Str255 outDescriptor) const;
The parameters for this method are:
Return:
Returns a pointer that is the same as outDescriptor.
Purpose:
Determine the location of the image within a View.
Access:
Prototype:
void GetImageLocation(SPoint32 &outLocation) const;Parameters:
The parameter for this method is:
Return:
Purpose:
Pass back the dimensions of a View's image.
Access:
Prototype:
virtual void GetImageSize(Parameters:
SDimension32 &outSize) const;
The parameter for this method is:
Return:
Purpose:
Retrieve a pointer to the view that has the focus. This is an accessor method for the sInFocusView data member.
Access:
Prototype:
static LView* GetInFocusView();Parameters:
Return:
The pointer to the LView that has the focus.
Purpose:
Return the region, in local coordinates, to which update drawing is clipped. This is an override of GetLocalUpdateRgn() in LPane.
Purpose:
Pass back the coordinate origin for the Port needed to set up the local coordinates of a View.
Access:
Prototype:
virtual void GetPortOrigin(Point &outOrigin) const;Parameters:
The parameter for this method is:
Return:
Purpose:
Retrieve the Rect from mRevealedRect.
Access:
Prototype:
void GetRevealedRect( Rect &outRect ) const;Parameters:
The parameter for this method is:
|
Return:
Purpose:
Pass back the location of a View's frame within its image.
Access:
Prototype:
virtual void GetScrollPosition(Parameters:
SPoint32 &outScrollPosition) const;
The parameter for this method is:
Return:
Purpose:
This method retrieves the value of mScrollUnit.
Access:
Prototype:
void GetScrollUnit(Parameters:
SPoint32 &outScrollUnit ) const;
The parameter for this method is:
|
Return:
Purpose:
This method returns the value of mSubPanes.
Access:
Prototype:
TArray<LPane*>& GetSubPanes();Parameters:
Return:
A reference to an array that contains mSubPanes.
Purpose:
Get the Value of the Pane of a View which has the specified ID. The Pane may be the View itself, or a subpane of the View.
Access:
Prototype:
virtual SInt32 GetValueForPaneID(Parameters:
PaneIDT inPaneID ) const;
The parameter for this method is:
Return:
Returns the value in an SInt32.
Purpose:
Make a View invisible. This is an override of Hide() in LPane.
Purpose:
Return whether a Point specified in Image Coords is within the Frame of a View.
Access:
Prototype:
Boolean ImagePointIsInFrame(Parameters:
SInt32 inHorizImage,
SInt32 inVertImage ) const;
The parameters for this method are:
Return:
Boolean indicating whether the point is in the frame (true) or not (false).
Purpose:
Determine whether a rectangle specified in image coordinates intersects the frame of a View.
Access:
Prototype:
Boolean ImageRectIntersectsFrame(Parameters:
SInt32 inLeftImage,
SInt32 inTopImage,
SInt32 inRightImage,
SInt32 inBottomImage ) const;
The parameters for this method are:
Return:
Boolean indicating whether the rectangle is in the frame (true) or not (false).
Purpose:
Convert point from Image (32-bit) to Local (16-bit) coordinates.
Image and Local coordinates are different only when the Image size is greater than 16K (15-bit).
Access:
Prototype:
void ImageToLocalPoint(Parameters:
const SPoint32 &inImagePt,
Point &outLocalPt ) const;
The parameters for this method are:
Return:
Purpose:
Access:
Prototype:
void InitView( const SViewInfo &inViewInfo );Parameters:
The parameter for this method is:
Return:
Purpose:
Convert point from Local (16-bit) to Image (32-bit) coordinates.
Image and Local coordinates are different only when the Image size is greater than 16K (15-bit)
Access:
Prototype:
void LocalToImagePoint(Parameters:
const Point &inLocalPt,
SPoint32 &outImagePt ) const;
The parameters for this method are:
Return:
Purpose:
Convert point from Local to Port coordinates. This is an override of LocalToPortPoint() in LPane.
Purpose:
Move the location of the Image and Frame by the specified amounts. This is an override of MoveBy() in LPane.
Purpose:
Adjust the Enabled, Active, and Visible properties of all subpanes.
This function is for the convenience of people who have code from CW5 (PowerPlant 1.0.2) and earlier which created Panes directly in the code (not from 'PPob' resources). You really should call FinishCreate() for each Pane, but to quickly get code running, you can call this function after creating several Panes inside one View.
Do NOT use this function for new code.
Access:
Prototype:
void OrientAllSubPanes();Parameters:
Return:
Purpose:
Adjust the Enabled, Active, and Visible properties of a subpane based on the properties of this View (which must be the subpane's SuperView).
Access:
Prototype:
virtual void OrientSubPane( LPane *inSub );Parameters:
The parameter for this method is:
Return:
Purpose:
Notify the View system that a View is no longer in focus.
Call when the coordinate system or clipping region of a View changes, passing a pointer to that View. This clears the saved focus if that View was the one in focus.
Use nil for inView if you manually change (and don't restore) the current
port or clipping region
Access:
Prototype:
static void OutOfFocus( LView *inView );Parameters:
The parameter for this method is:
Return:
Purpose:
Convert a point from Port to local coordinates. This is an override of PortToLocalPoint() in LPane.
Purpose:
Try to print a panel of a View. The View is at the top level of the Printout, meaning that it controls pagination. This functions scrolls the View to the specified panel.
This is an override of PrintPanel() in LPane.
Purpose:
Adjusts the Image so that it fits within the Frame. This function addresses the problem of what to do when you scroll a View to at or near the bottom or right, then make the View's frame larger. This would normally expose some undefined area below or to the right of the image.
If mReconcileOverhang is true, this function scrolls the image so that the bottom right corner is at the bottom right of the frame. However, it never moves the top left corner of the image beyond the top left of the frame. Therefore, the only time undefined area is exposed is when the frame is larger than the Image.
For Views with fixed image sizes, such as drawings where the Image
size is the size of a printed page, set mReconcileOverhang to true. The user does not normally want to see past the bottom or right
of such Views.
For Views with variable Image sizes, such as text blocks where
the size of the Image depends on the number of lines of text,
set mReconcileOverhang to false. The user may want to see the undefined area in anticipation
of the image growing.
Access:
Prototype:
virtual void ReconcileFrameAndImage(Parameters:
Boolean inRefresh );
The parameter for this method is:
Return:
Purpose:
Invalidate the area occupied by a View. This forces an Update event that, when processed, will redraw the View. Refresh does nothing if the View is not visible. This is an override of Refresh() in LPane.
Purpose:
You should not normally call this function. Call LPane::PutInside(nil) to remove a SubPane from its SuperView
Access:
Prototype:
virtual void RemoveSubPane(Parameters:
LPane *inSub);
The parameter for this method is:
Return:
Purpose:
Change the Frame size by the specified amounts. This is an override of ResizeFrameBy() in LPane.
Purpose:
Change the image size by the specified pixel increments.
Access:
Prototype:
virtual void ResizeImageBy(Parameters:
SInt32 inWidthDelta,
SInt32 inHeightDelta,
Boolean inRefresh );
The parameters for this method are:
Return:
Purpose:
Set the image size to the specified pixel dimensions.
Access:
Prototype:
void ResizeImageTo(Parameters:
SInt32 inWidth,
SInt32 inHeight,
Boolean inRefresh );
The parameters for this method are:
Return:
Purpose:
Read size and location information stored in a Stream by the SavePlace() function. This is an override of RestorePlace() in LPane.
Purpose:
Write size and location information to a Stream for later retrieval by the RestorePlace() function. This is an override of SavePlace() in LPane.
Purpose:
Scroll the pixels of a View. This method is called internally by ScrollImageBy() to shift the pixels.
Access:
Prototype:
virtual void ScrollBits(Parameters:
SInt32 inLeftDelta,
SInt32 inTopDelta ) ;
The parameters for this method are:
Return:
Purpose:
Scroll image by specified horizontal and vertical increments. Scrolling moves the image relative to the frame and port, so that a different portion of the image is visible thru the frame.
Positive deltas scroll right and down. Negative deltas scroll left and up.
If inRefresh is true, the Port containing the View is updated immediately, rather than refreshed at the next update event. Scrolling usually happens during mouse down tracking, so we want immediate visual feedback.
Access:
Prototype:
virtual void ScrollImageBy(Parameters:
SInt32 inLeftDelta,
SInt32 inTopDelta,
Boolean inRefresh );
The parameters for this method are:
Return:
Purpose:
Scroll image to the specified horizontal and vertical locations.
Scrolling moves the image relative to the frame and port, so that a different portion of the image is visible thru the frame.
When scrolled to (0, 0), the top left of the image coincides with the top left of the frame (home position).
If inRefresh is true, the Port containing the View is updated immediately,
rather than refreshed at the next update event. Scrolling usually
happens during mouse down tracking, so we want immediate visual
feedback.
Access:
Prototype:
void ScrollImageTo(Parameters:
SInt32 inLeftLocation,
SInt32 inTopLocation,
Boolean inRefresh );
The parameters for this method are:
Return:
Purpose:
Scroll image by specified horizontal and vertical increments, but don't scroll beyond an edge of the frame.
Access:
Prototype:
virtual Boolean ScrollPinnedImageBy(Parameters:
SInt32 inLeftDelta,
SInt32 inTopDelta,
Boolean inRefresh );
The parameters for this method are:
Return:
Return true if the View actually scrolls, else false.
Purpose:
Scroll View Image to the specified panel. This is an override of ScrollToPanel() in LPane.
Purpose:
Set the descriptor of the Pane of a View which has the specified ID. The Pane may be the View itself, or a subpane of the View.
Access:
Prototype:
virtual void SetDescriptorForPaneID(Parameters:
PaneIDT inPaneID,
ConstStr255Param inDescriptor );
The parameters for this method are:
Return:
Purpose:
Specify whether to reconcile the Frame and Image when there is overhang. Refer to ReconcileFrameAndImage() to learn more.
Access:
Prototype:
void SetReconcileOverhang( Boolean inSetting );Parameters:
The parameter for this method is:
|
Return:
Purpose:
Set the mScrollUnit data member.
Access:
Prototype:
void SetScrollUnit( const SPoint32 &inScrollUnit );Parameters:
The parameter for this method is:
|
Return:
Purpose:
Set the value of the pane of a View which has the specified ID. The pane may be the View itself, or a subpane of the View.
Access:
Prototype:
virtual void SetValueForPaneID(Parameters:
PaneIDT inPaneID,
SInt32 inValue );
The parameters for this method are:
Return:
Purpose:
Make a View visible. This is an override of Show() in LPane.
Purpose:
This method gets called as notification that the image of some SubView changed size, location, or scroll units. You should override this method to respond to such changes.
Access:
Prototype:
virtual void SubImageChanged( LView* inSubView );Parameters:
The parameter for this method is:
Return:
Purpose:
The SuperView of a View has been activated. This is an override of SuperActivate() in LPane.
Purpose:
The SuperView of a View has been deactivated. This is an override of SuperDeactivate() in LPane.
Purpose:
The SuperView of a View has been disabled. This is an override of SuperDisable() in LPane.
Purpose:
The SuperView of a View has been enabled. This is an override of SuperEnable() in LPane.
Purpose:
This is called when the SuperView of a View has been hidden. This is an override of SuperHide() in LPane.
Purpose:
This is called when the SuperView is printing a panel. This is an override of SuperPrintPanel() in LPane.
Purpose:
The SuperView of a View has become visible. This is an override of SuperShow() in LPane.
Purpose:
The pointer to the LView that has the focus.
Access:
Prototype:
static LView *sInFocusView;
Purpose:
Access:
Prototype:
SDimension32 mImageSize;
Purpose:
Access:
Prototype:
SPoint32 mImageLocation;
Purpose:
Access:
Prototype:
SPoint32 mScrollUnit;
Purpose:
Access:
Prototype:
Point mPortOrigin;
Purpose:
A list of the subpanes for this View.
Access:
Prototype:
TArray<LPane*> mSubPanes;
Purpose:
Access:
Prototype:
Rect mRevealedRect;
Purpose:
The handle to the update region.
Access:
Prototype:
RgnHandle mUpdateRgnH;
Purpose:
The value indicating whether to reconcile overhang.
Access:
Prototype:
Boolean mReconcileOverhang;