View object, which manages the display of a rectangular area in a window. More...
Public Member Functions
|Window_t *||ParentWindow () const|
|View_t *||ParentView () const|
|virtual void||SetMinMaxSize (float min_width, float max_width, float min_height, float max_height)|
|float||MinWidth () const|
|float||MaxWidth () const|
|float||MinHeight () const|
|float||MaxHeight () const|
|const Rect_t &||LBounds () const|
|const Rect_t &||PFrame () const|
|void||SetPFrame (const Rect_t &pframe)|
|void||Invalidate (const Rect_t &rect)|
|int||CountChildren () const|
|View_t *||HeadChild () const|
|View_t *||TailChild () const|
|virtual void||SetBrush (const Color_t &color, float brush_width=1, line_cap_type_t cap_type=eLCT_butt_extended_half_width)|
|virtual void||SetFillColor (const Color_t &color)|
|virtual void||DrawLine (const Point_t &from, const Point_t &to, bool anti_alias=true)|
|virtual void||DrawRect (const Rect_t &rect, bool anti_alias=true, bool fill=false)|
|virtual void||DrawText (const String_t &string, const Point_t &where, bool anti_alias=true)|
|void||SetFont (const Font_t &font)|
Static Public Member Functions
|static float||RealPlatformSpacing (float spacing_constant)|
Protected Member Functions
|virtual void||AddChild (View_t *child)|
|virtual View_t *||RemoveChild (View_t *child)|
|virtual void||LBoundsChanged (const Rect_t &old_lbounds, const Rect_t &new_lbounds)|
|virtual void||ChildMinMaxSizeChanged (View_t *child)|
|virtual void||Paint (const Region_t &clip_to)|
|virtual void||SetBackgroundColor (const Color_t &color)|
|Color_t||BackgroundColor () const|
|void||SetClearBackgroundBeforePaint (bool clear_before_paint)|
|virtual void||MouseChanged (const Point_t &point, bool mouse_inside_view, bool left_mouse_button_down, bool left_mouse_button_double_clicked, bool right_mouse_button_down_if_present)|
|virtual void||TrackMouseUntilButtonsReleased (bool enable=true)|
Non-core library: UTgui
A view object manages the rendering of itself and its child views for a rectangular area in a window. In Windows parlance, a view is still a window. In GTK parlance, a view is a GtkContainer and its GtkWidget base class rolled into one. In MacOS Cocoa parlance, a view is an NSView.
It is in the views that actual rendering occurs. A window must contain a single root view, installed by the subclass derived from Window_t. Typically, that single view implements rendering of the entire content of the window, or is merely a container for a number of other views. A view can, optionally, contain any number of child views contained within its boundaries. Child views can even cross the edges of their parent, but they will be clipped such that their visible area is constrained to that of their parent.
The value space is that which is typically used is that for a monitor, with increasing x values to the right and increasing y values to the bottom. Floating point numbers are used by the UTgfx and UTgui libraries to represent screen display because for scaling, use of floating point computation until final conversion to an integer coordinate is more efficient than use of integers when scaling. That way the same interface can be used to render to the display, printer, and so on. Floats are accurate to within c_dbl_abs_min_denominator out to about 4,000,000.
View constructor. After construction, a view can be added to a window if it is the root view, or as a child of another view.
|Window_t * View_t::ParentWindow||(||)|| const
|View_t * View_t::ParentView||(||)|| const
|virtual void View_t::SetMinMaxSize||(||float||min_width,|
Sets the minimum and maximum sizes for the view. The minimum values must be greater than or equal to zero (which correspond to a visible width of one pixel). If the maximum values are -1, the view does not have a maximum size.
Reimplemented in Button_t.
|float View_t::MinWidth||(||)|| const
|float View_t::MaxWidth||(||)|| const
|float View_t::MinHeight||(||)|| const
|float View_t::MaxHeight||(||)|| const
|const Rect_t & View_t::LBounds||(||)|| const
Returns the local boundary, in local coordinates. If this view is not a Viewport_t or subclass of Viewport_t, the upper left corner will always be at x=0, y=0. If the view can be resized, the returned value will reflect the minimum size until the view has actually been created in a parent window.
Floating point numbers are used by the UTgfx and UTgui libraries to represent screen display because for scaling, use of floating point computation until final conversion to an integer coordinate is more efficient than use of integers when scaling. That way the same interface can be used to render to the display, printer, and so on. Floats are accurate to within c_dbl_abs_min_denominator out to about 4,000,000. If this view is a Viewport_t or subclass of Viewport_t and the content rect under the view port could potentially be larger than that, another design should be used with a higher-precision value (perhaps an int64) used to represent the underlying content. In that case, the view should convert to floating point numbers for display purposes after shifting to a local frame with the upper left corner being at x=0, y=0.
|const Rect_t & View_t::PFrame||(||)|| const
|void View_t::SetPFrame||(||const Rect_t &||pframe||)|
Sets the view's frame in the parent view or window coordinates. This priviledge should generally be reserved for the parent. Views should instead request their own size allocation by way of SetMinMaxSize. The PFrame of a root view can never be set explicitly once it has been installed.
Causes the entire view and its children to be repainted asynchronously.
|void View_t::Invalidate||(||const Rect_t &||rect||)|
Causes a portion of the view and any overlapping parts of its children to be repainted asynchronously.
|int View_t::CountChildren||(||)|| const
|View_t * View_t::HeadChild||(||)|| const
|View_t * View_t::TailChild||(||)|| const
|static float View_t::RealPlatformSpacing||(||float||spacing_constant||)||
Converts a spacing constant to a platform-specific spacing. The spacing constant must be one of these:
|virtual void View_t::AddChild||(||View_t *||child||)||
Adds a child view. Children may not be added while a paint operation is in progress.
Removes a child view. Children may not be removed while a paint operation is in progress.
|virtual void View_t::LBoundsChanged||(||const Rect_t &||old_lbounds,|
|const Rect_t &||new_lbounds|
Called when the view's lbounds (local boundary, but not necessarily frame in the parent's coordinate system) has changed. This is typically due to the view having been resized, although if this view is a subclass of Viewport_t, this could be due to scrolling. When this function is called, the lbounds of the view will already have been updated to the new lbounds. If this view is not a Viewport_t subclass, the upper left corner will always be at x=0, y=0.
|virtual void View_t::ChildMinMaxSizeChanged||(||View_t *||child||)||
Notification when a child view's min/max size has been changed. This will be called from within child->SetMinMaxSize. If a size change is needed and the parent view subclass does not reset the child's PFrame to comply with the new requirements, the child's PFrame will be resized to comply. This function will be invoked even if no change to the child view size is required, and even if the change merely reflects a transition state during a sequential process of multiple child view changes.
|virtual void View_t::Paint||(||const Region_t &||clip_to||)||
Called when the view should be painted. If the view has an OS peer which performs its own painting (for example, a button), the class implementation will paint the view using the OS default painting mechanism. From within Paint, any drawing operations like DrawLine that overlap outside the clip_to region will be cropped or, if completely outside the clip_to region, discarded. The region coordinates are local to the view. Any child views' frames will have been removed.
The view will be erased to its background color before Paint is invoked. If the background color is transparent (alpha = 0) the background will not be drawn first. This would be appropriate if the view class will draw every pixel within the view bounds, or if it is a child of a parent view whose background color the child view should inherit, painting over the parent's background color.
The view can call the parent class Paint function, then paint over what the parent class painted if so desired.
Because a view's edges are specified in coordinates for which integers are at the middle of a pixel which is deemed to be included in the view, the view bounds are, for painting purposes, expanded by a half pixel. This is reflected in the clip_to region. If a view had bounds of (10, 10, 20, 20) and were to be entirely painted, the clip_to region would be comprised of a single rectangle whose coordinates would be (9.5, 9.5, 20.5, 20.5).
Reimplemented in Button_t.
|virtual void View_t::SetBackgroundColor||(||const Color_t &||color||)||
Sets the view background color and invalidates the entire view including any children whose background color is transparent. The color must have an alpha value of 255 for fully opaque or 0 for fully transparent. By default, any view will have a transparent background. The default background color for a window is that which would be appropriate for a dialog. If the root view is transparent, it will be colored appropriately for a dialog.
|Color_t View_t::BackgroundColor||(||)|| const
Returns the view's background color. If it is transparent but has a parent view and/or window, the parent hierarchy will be traversed until something is found which is opaque, in which case that color is returned, or the whole hierarchy is found to be transparent, in which case a Color_t with an alpha value of 0 is returned.
Sets whether a view's background should be cleared to its background color before its Paint function is called. By default, the background is cleared. This function is used as an optimization with clear_before_paint = false if every single pixel in the painted clip_to region will be painted, so there's no point in clearing the view to the background color before painting.
|virtual void View_t::MouseChanged||(||const Point_t &||point,|
Virtual function invoked when the mouse is moving over the view, but not over any of its children. If a child view has a parent view (as opposed to being the root window) and needs to propogate this call up though, it can of course convert the point to its parent's coordinate system and call the parent's MouseChanged function. MouseChanged will be called whenever mouse button states change. Note that the right mouse button might not be physically present, especially on Apple hardware. That being the case, any functions that would be accessed through the right button MUST be available by other means. For example, all context menu options available by right clicking on something should also be available from the main menu. This is important on other operating systems as well, because the availability of a context menu might not be obvious to all users. MouseChanged will be called once after the mouse has left the view, either by moving outside its lbounds or onto another window that is higher in the Z-order and overlapping with this view in X and Y. A view may not delete itself inside this call. If a view subclass needs to respond to the MouseChanged event in that way, it must do so asynchronously (by sending a message to a MessageReceiver_t in the App_t nessage loop, probably itself).
Reimplemented in Button_t.
|virtual void View_t::TrackMouseUntilButtonsReleased||(||bool|| enable =
If track_even_outside_view is true, then the view will continue to receive MouseChanged calls, even if the mouse leaves the view lbounds. If enable is false, then any tracking that was previously engaged will be canceled. This function is not reference counted, so it cannot be used by multiple layers of inheritance unless the child class overrides this function in order to take into consideration the requirements of its parent class. Tracking will automatically be canceled when all mouse buttons have been released. At that point, if the mouse is outside the view, then one last call to MouseChanged will be made to communicate the final state before tracking is cancelled. Tracking can only be enabled from inside a call to MouseChanged, with the left or right mouse button having been down at the time. While tracking is enabled, no other views will receive MouseChanged events.
|virtual void View_t::SetBrush||(||const Color_t &||color,|
|float|| brush_width =
|line_cap_type_t|| cap_type = |
Sets the brush to be used for subsequent drawing operations. This can be called any time.
Reimplemented from Drawable_t.
|virtual void View_t::SetFillColor||(||const Color_t &||color||)||
Sets the color to be used when drawing a filled shape as opposed to just the outline of the shape. The outline is always drawn using the color specified by SetBrush.
Reimplemented from Drawable_t.
|virtual void View_t::DrawLine||(||const Point_t &||from,|
|const Point_t &||to,|
|bool|| anti_alias = |
Draws a line from the specified point to the specified point. If anti_alias is true, the line will be drawn using anti-aliasing. If anti_alias is false and the brush width is odd, from and to will be rounded to the nearest pixel boundary. If anti_alias is false and the brush width is even, from and to will be rounded to the nearest half-pixel boundary.
|virtual void View_t::DrawRect||(||const Rect_t &||rect,|
|bool|| anti_alias =
|bool|| fill = |
Draws a rectangle. If fill is true, the rectangle is filled with the fill color specified by SetFillColor. If anti_alias is false and the brush width is odd, from and to will be rounded to the nearest pixel boundary. If anti_alias is false and the brush width is even, from and to will be rounded to the nearest half-pixel boundary. If the selected brush uses end cap type eLCT_butt_extended_half_width or eLCT_round, the end cap type will be ignored. The rectangle will not have rounded or notched corners, or rounded inside edges.
|virtual void View_t::DrawText||(||const String_t &||string,|
|const Point_t &||where,|
|bool|| anti_alias = |
Draws the specified text at the specified point. The point is on the baseline, on the left side of the string. If the string is rendered right to left, it will be, and the end of the string will be aligned to where.x. Right-to-left text in the middle of a left-to-right string will be rendered in flipped form. If anti_alias is true, the string will be rendered using anti-aliasing. This can only be called inside of Paint().
|void View_t::SetFont||(||const Font_t &||font||)|
Sets the font to be used for rendering text. It might defer to another font for characters which it does not support.
Reimplemented from Drawable_t.