Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TSimpleView
Inherited By:
None.
Purpose:
Facilitates either of two frequently encountered needs:
- To attach a border to a label.
- To attach a label to a view and optionally enclose that view with a border.
A TLabelView specially handles up to three graphic elements:
- A special child view, called the content.
- A label.
- A rectangular border. When both a content and a border are included, the content view is calculated to fit inside the border.
The label can be positioned at the center of the border, or on or near any of the four sides of the border. The default position of the label is at the center of the rectangular border. That default is convenient if you use TLabelView merely to put a border around a label.
If the label is positioned at a side (called an Edge in the function names), you can choose where along that side's axis the label will be. The flexible positioning of a label around any border-edge allows you great flexibility when labeling the content with the label.
The label can have a margin around it, referred to as the label's margin. The border can have a margin associated with it, too, referred to as just the margin. Each margin forms a zone that excludes each other graphic element and its margin.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
None.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TLabelView ()
- TLabelView (TLabel * adopted, TBorder * border =NIL)
- TLabelView (const TLabelView & copy)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a new TLabelView and initializes its label and border to those specified.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Call this function directly.
- Called to copy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::operator=
TLabelView & operator =(const TLabelView & copy)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::operator>>=
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & -The stream to which the object streams itself out.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::operator<<=
virtual TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & -The stream from which the object streams itself in.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws TInvalidVersionError if it encounters an object whose version number indicates it cannot be streamed in. Passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::AdoptLabel
virtual void AdoptLabel (TLabel * label)
Interface Category:
API.
Purpose:
Adopts the specified label as the one to display. This function deletes the previously adopted label and resets the view's allocated area.
Calling Context:
Call this function directly.
Parameters:
- TLabel * label -The label to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::OrphanLabel
virtual TLabel * OrphanLabel ()
Interface Category:
API.
Purpose:
Orphans the current label. This function does not delete the orphaned label.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the orphaned label.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::GetLabel
virtual TLabel * GetLabel () const
Interface Category:
API.
Purpose:
Returns the current label.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the current label.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::AdoptBorder
virtual void AdoptBorder (TBorder * border)
Interface Category:
API.
Purpose:
Adopts the specified border as the one to display. This function deletes the previously adopted border.
Calling Context:
Call this function directly.
Parameters:
- TBorder * border -The border to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::OrphanBorder
virtual TBorder * OrphanBorder ()
Interface Category:
API.
Purpose:
Orphans the current border. This function does not delete the orphaned border.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the orphaned border.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::GetBorder
virtual TBorder * GetBorder () const
Interface Category:
API.
Purpose:
Returns the current border.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the current border.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::GetPreferredSize
virtual TGPoint GetPreferredSize () const
Interface Category:
API.
Purpose:
Computes and returns the preferred size of this view. The preferred size is the height and width that fully enclose the border and the label.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TGPoint whose x component is the preferred width of the view, and whose y component is the preferred height.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::DrawContents
virtual void DrawContents (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws the border and the label to the specified TGrafPort.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::HandlePostLayout
virtual void HandlePostLayout ()
Interface Category:
API.
Purpose:
Performs post-layout processing. The framework calls this function after the framework has laid out the parts of the label-view. HandlePostLayout prompts the label-view to integrate its previously-adopted content view into its interior bounds by calling the content view's SetAllocatedAreaInParent function.
Calling Context:
You should not call this function directly; the framework does it instead.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The implementation of this function relies on the public, virtual function GetInteriorBounds to tell the TLabelView what rectangular area can be safely used for the content view. If a derived class overrides GetInteriorBounds, it affects HandlePostLayout as well.
Member Function: TLabelView::GetLayout
virtual void GetLayout (TGRect & labelBounds, TGRect & borderBounds, TGRect & interiorBounds) const
Interface Category:
API.
Purpose:
Calculates the layout of the various pieces and loads the results into the parameters passed as references.
Calling Context:
Call this function directly. The framework also calls this this function to layout the pieces when you do something that affects the layout such as adopting a new element or setting a margin or other positioning parameter.
Parameters:
- TGRect & labelBounds -Encloses the label and the margin around the label.
- TGRect & borderBounds -Encloses the previously adopted border and the label and a margin around the label.
- TGRect & interiorBounds -The area that can be used for a content view. The calculation of this region clips off any area inside the border that the margin and the label and the label's margin consume.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overloading this function changes the way the framework lays out the pieces when you do something that affects the layout such as adopting a new element or setting a margin or other positioning parameter.
Member Function: TLabelView::GetBounds
virtual void GetBounds (TGArea & area) const
Interface Category:
API.
Purpose:
Reports the area of the TLabelView. That area is the smallest rectangle enclosing the label, its margin, and the border and the border's margin.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The bounds are reported in the local coordinates of the TLabelView. GetBounds reports the same size as GetPreferredSize, but in the format of a TGArea instead of a TGPoint.
Member Function: TLabelView::GetInteriorBounds
virtual TGRect GetInteriorBounds () const
Interface Category:
API.
Purpose:
Returns the interior bounds, the area inside the label view that you can safely use for child views. The bounds and margin of the adopted border restrict the interior bounds. So do the bounds and margin of the adopted label, if the label is inside the border or on top of one of the border's sides.
Calling Context:
Call this function directly.
Parameters:
Return Value:
TGRect -Encloses the area that can safely be used for the content view.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overriding this function affects HandlePostLayout as well.
Member Function: TLabelView::GetMargin
virtual GCoordinate GetMargin () const
Interface Category:
API.
Purpose:
Reports the separation between the border and the content view.
Calling Context:
Call this function directly.
Parameters:
Return Value:
GCoordinate margin -The distance separating the border from other graphic elements and their margins.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The margin can be assigned by the function SetMargin.
The margin also affects the separation between the border and the label.
Member Function: TLabelView::SetMargin
virtual void SetMargin (GCoordinate margin)
Interface Category:
API.
Purpose:
Controls the separation between the border and the content view.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate margin -The distance separating the border from the content view and from the label and its margin.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The margin can be read with GetMargin. If this function is never called, the border's margin defaults to kDefaultMargin.
If the label is positioned just inside or outside the border, the separation between the border and the label is the sum of the margin plus the label's margin.
Member Function: TLabelView::GetEdgeOffset
virtual EEdgeOffset GetEdgeOffset () const
Interface Category:
API.
Purpose:
Reports whether the label is just inside the border, just outside the border, or coaxial with one of the border's sides. Coaxial here means that the label is centered on the side, somewhere along the side's length.
Calling Context:
Call this function directly.
Parameters:
Return Value:
- EEdgeOffset delta -Defined inside TLabelView to have possible discrete values of: kInside, kOver, or kOutside.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is only meaningful when SetBorderEdge places the label at one of the border's sides (instead of at the center of the border, which is the label's default position).
You can change the edge offset with the function SetEdgeOffset.
Member Function: TLabelView::SetEdgeOffset
virtual void SetEdgeOffset (EEdgeOffset delta)
Interface Category:
API.
Purpose:
Assigns the label to be either just inside the border, just outside the border, or coaxial with one of the border's sides. Coaxial here means that the label is centered on the side, somewhere along the side's length.
Calling Context:
Call this function directly.
Parameters:
- EEdgeOffset delta -Defined inside TLabelView to have possible discrete values of: kInside, kOver, and kOutside.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function only has effect when SetBorderEdge chooses one of the border's sides for label placement (instead of choosing the center of the border, which is the label's default placement).
You can read the edge offset with the function GetEdgeOffset.
The default edge offset is kOver, which centers the label somewhere over the border's side.
Member Function: TLabelView::GetLabelJustification
virtual EJustificationAlongEdge GetLabelJustification () const
Interface Category:
API.
Purpose:
Reports where on the specified border-side the label is positioned. For example, if the border-side is kTop, then kAlignMinimum puts it on the top left, kAlignMax puts it on the top right and kAlignCenter puts it on the top in the center.
Calling Context:
Call this function directly.
Parameters:
Return Value:
EJustificationAlongEdge -Defined inside TLabelView to have possible discrete values of: kEdgeMinimum, kEdgeMaximum, or kEdgeCenter.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
You can control the justification with SetLabelJustification.
Member Function: TLabelView::SetLabelJustification
virtual void SetLabelJustification (EJustificationAlongEdge alignment)
Interface Category:
API.
Purpose:
Assigns where on the specified border-side the label is positioned. For example, if the border-side is kTop, then kAlignMinimum puts it on the top left, kAlignMax puts it on the top right and kAlignCenter puts it on the top in the center.
Calling Context:
Call this function directly.
Parameters:
- EJustificationAlongEdge alignment -Defined inside TLabelView to have possible discrete values of: kEdgeMinimum (which places the label near one end of the border side), kEdgeMaximum (which places the label near the other end of the border side), or kEdgeCenter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function only has effect when SetBorderEdge chooses one of the border's sides for label placement (instead of choosing the center of the border, which is the label's default placement).
You can read the justification with the function GetLabelJustification.
The default justification is kEdgeCenter.
Member Function: TLabelView::GetBorderEdge
virtual EBorderEdge GetBorderEdge () const
Interface Category:
API.
Purpose:
Reports whether the label is in the center of the border, or associated with the top, bottom, left, or right side of the border.
Calling Context:
Call this function directly.
Parameters:
Return Value:
EBorderEdge whichSideOrCenter -Defined inside TLabelView to have possible discrete values of: kLeft, kTop, kRight, kBottom, or kCenter.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
You can move the label to a different side of, or the center of the border, with the function SetBorderEdge.
Member Function: TLabelView::SetBorderEdge
virtual void SetBorderEdge (EBorderEdge location)
Interface Category:
API.
Purpose:
Assigns the label to be in the center of the border, or associated with the top, bottom, left, or right side of the border. The default is to place the label at the center of the rectangular border. That default is convenient when you use TLabelView to merely place a border around the label. Otherwise, if you are using TLabelView to label another view (the content) you probably will place the label near one of the border's sides.
Calling Context:
Call this function directly.
Parameters:
- EBorderEdge location -Defined inside TLabelView to have possible discrete values of: kLeft, kTop, kRight, kBottom, or kCenter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
You can perform fine-tuning of the label's position relative to a side of the border (and therefore relative to the content view inside the border) by using the functions SetEdgeOffset, SetLabelJustification, SetLabelMargin, or SetLabelInset.
You can use the function GetBorderEdge to read which border side (if any) the label is near.
Member Function: TLabelView::GetContentView
virtual TView * GetContentView () const
Interface Category:
API.
Purpose:
Provides a pointer to the adopted content view so that you can inspect or modify it.
Calling Context:
Call this function directly.
Parameters:
Return Value:
TView * adoptedChildView -The subview which is enclosed in the border, or labeled, or both labeled and enclosed in the border.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function returns what AdoptContentView installs and what OrphanContentView releases.
Member Function: TLabelView::OrphanContentView
virtual TView * OrphanContentView ()
Interface Category:
API.
Purpose:
Releases the content view.
Calling Context:
Call this function directly.
Parameters:
Return Value:
TView * orphanedChildView -The subview which was enclosed in the border, or labeled, or both labeled and enclosed in the border.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function removes what AdoptContentView installs and what GetContentView accesses.
This function does not delete the content view it orphans.
Member Function: TLabelView::AdoptContentView
virtual void AdoptContentView (TView * view)
Interface Category:
API.
Purpose:
Installs a child view so that it can be optionally labeled and optionally enclosed in a border. The child view that can have such special treatment facilitated by TLabelView is called the content.
Calling Context:
Call this function directly.
Parameters:
- TView * contentView -The subview which can get enclosed by the border, or labeled, or both enclosed by the border and labeled.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function installs what OrphanContentView removes and what GetContentView accesses.
Member Function: TLabelView::HandleAllocatedAreaChanged
virtual void HandleAllocatedAreaChanged (const TGArea & newArea)
Interface Category:
API.
Purpose:
Prompts the control to adjust its layout when its parent view changes the area allocated to the control.
Calling Context:
Do not call this function directly. The framework calls it when there is a change to the allocated area of the child view. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.
Parameters:
- const TGArea & newArea -A reference to the new TGArea object.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::NeedsClipping
virtual bool NeedsClipping ()
Interface Category:
API.
Purpose:
Checks during the drawing operation whether the view needs to be clipped to fit within its bounds. If this returns true, it forces the View system to check that the view fits its bounds. During construction, it is initialized to false and recalculated internally depending on the allocated area.
If your view can guarantee that it and its children will draw within its allocated area, override this function to return false. The View system can use this fact to optimize drawing.
Calling Context:
Called by the View system. Derived classes can override this and if returned value is set to false, they must ensure that the view (or its children) does not draw beyond its bounds.
Parameters:
Return Value:
Returns true if the view clipped to its allocated area during a draw operation, else the return value is false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::IsEnabled
virtual bool IsEnabled () const
Interface Category:
API.
Purpose:
Reports whether this label is enabled. Typically, labels have different looks for enabled and disabled states.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if this label is active.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::SetEnabled
virtual void SetEnabled (bool enabled)
Interface Category:
API.
Purpose:
Enables or disables this label according to the specified flag. Typically, labels have different looks for enabled and disabled states.
Calling Context:
Call this function directly.
Parameters:
- bool enabled -The flag indicating whether to enable or disable this label. True enables the label; false disables it.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::IsActive
virtual bool IsActive () const
Interface Category:
API.
Purpose:
IsActive reports whether this label is active. Labels usually have different looks for active and inactive states.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if this label is active.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::SetActive
virtual void SetActive (bool active)
Interface Category:
API.
Purpose:
Activates or deactivates the label, according to the specified flag. (Labels usually have different looks for active and inactive states.)
Calling Context:
Call this function directly.
Parameters:
- bool active -The flag indicating whether to set this label to be active or inactive. True sets the label to be active; false sets the label to be inactive.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::GetBackgroundColor
virtual TRGBColor GetBackgroundColor () const
Interface Category:
API.
Purpose:
Return the background color of the control.
Calling Context:
Call this function directly.
Parameters:
Return Value:
TRGBColor.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::SetBackgroundColor
virtual void SetBackgroundColor (const TColor & backgroundColor)
Interface Category:
API.
Purpose:
Allows you to set the background color of control.
Calling Context:
Call this function directly.
Parameters:
- const TColor & backgroundColor -The color to be set.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TLabelView::GetLabelInset
virtual GCoordinate GetLabelInset () const
Interface Category:
API.
Purpose:
Return the inset between the label (which might already has some margin) and the border. However, if label is set to be outside of the border, it insets from the side of view.
Calling Context:
Call this function directly.
Parameters:
Return Value:
GCoordinate inset -The inset between the label and the border/side of the view.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The inset can be assigned by the function SetLabelInset.
The inset also affects the separation between the border and the label.
Member Function: TLabelView::SetLabelInset
virtual void SetLabelInset (GCoordinate inset)
Interface Category:
API.
Purpose:
Allows you to set the inset between the label and the border. However, if label is set to be outside of the border, it insets from the side of view.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate inset -The inset between the label and the border/side of the view.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The inset can be read with GetLabelInset. If this function is never called, the inset is default to kDefaultLabelInset.
Member Function: TLabelView::GetLabelMargin
virtual GCoordinate GetLabelMargin () const
Interface Category:
API.
Purpose:
Return the margin around the label.
Calling Context:
Call this function directly.
Parameters:
Return Value:
GCoordinate margin -The space around the label separating from other graphic elements.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The margin can be assigned by the function SetLabelMargin.
The margin also affects the separation between the label and the border similar to label inset, but this applies to all four sides of label.
Member Function: TLabelView::SetLabelMargin
virtual void SetLabelMargin (GCoordinate margin)
Interface Category:
API.
Purpose:
Allows you to set the margin around the label.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate margin -The space around the label separating from other graphic elements.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The margin can be read with GetLabelMargin. If this function is never called, the margin is default to kDefaultLabelMargin.
virtual ~ TLabelView ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.