Assists in drawing user manupulators for on-screen objects. More...

#include <owl/uihelper.h>

Public Types
enum	TWhere { TopLeft = 0 , TopCenter = 1 , TopRight = 2 , MidLeft = 3 , MidCenter = 4 , MidRight = 5 , BottomLeft = 6 , BottomCenter = 7 , BottomRight = 8 , Outside =-1 , Inside =-2 }
	Enumeration describing the location of a grapple selection. More...

enum	TStyle { HandlesIn = 0 , HandlesOut = 1 , Framed = 2 , DashFramed = 4 , Grapples = 8 , HatchBorder = 16 , HatchRect = 32 , InsideSpecial = 64 }
	Enumeration describing the type of grapples to be drawn. More...

Public Member Functions
	TUIHandle (const TRect &frame, uint style=HandlesIn\|Grapples\|HatchBorder, int thickness=5)
	Constructs a TUIHandle object for the specified frame, with eight grapples drawn in a hatched border and a default thickness of 5 pixels drawn to the inside.

void	MoveTo (int x, int y)
	Moves the rectangle to the given x and y coordinates.

void	Move (int dx, int dy)
	Moves the rectangle relative to the values specified in dx and dy.

void	Size (int w, int h)
	Sets the size of the rectangle according to the measurements specified in w, the width, and h, the height.

TRect	GetBoundingRect () const
	Calculate the outside frame rectangle.

TWhere	HitTest (const TPoint &point) const
	Compares a given point (point) to various parts of the rectangle.

void	Paint (TDC &dc) const
	Paints the TUIHandle object onto the specified device context, dc.

Static Public Member Functions
static uint16	GetCursorId (TWhere where)
	Helper function to convert a where code into a cursor shape Id.

Detailed Description

Assists in drawing user manupulators for on-screen objects.

TUIHandle manages and draws various kinds of UI handles, including hatched border handles, and resizing grapples (small squares that appear along the edges) on a rectangle. You can use this class to create a hatched border that encloses various kinds of drawing objects you want to manipulate.

With the help of this class, you can create an application that lets you

Resize the shape of the rectangle by pointing to and grabbing one of the grapples on the border
Move the entire rectangle by clicking in the middle of the rectangle

Although by default a hatched border with eight grapples is created, you can control whether grapples appear. In addition, you can vary the pattern of the border by drawing a dashed frame enclosing a rectangle or a rectangle filled with hatch marks. TuiHandle uses THatch8x8Brush to draw the hatched border.

TUIHandle uses the enum TWhere to return the area where the user points and clicks the mouse (referred to as a hit area).

The following diagram displays a UI handle and identifies several small square grapples where hit testing occurs.

The following code fragment sets up a hatched border and UI grapples for an OLE 2 container application:

// Do the default rectangle painting.
  .
  .
  .
TRect r //...; Insert your rectangle drawing code here.
 
// Draw 8 grapples with a border on top of the object.
TUIHandle handle(r, TUIHandle::HandlesIn|
                 TUIHandle::Grapples|
                 TUIHandle::HatchBorder, 5);
handle.Paint(dc);
// Insert your code here....
  .
  .
  .
// Draw a hatched border.
TUIHandle handle(r, TUIHandle::HatchBorder, 5);
handle.Paint(dc);

Definition at line 186 of file uihelper.h.

Member Enumeration Documentation

◆ TStyle

enum owl::TUIHandle::TStyle

Enumeration describing the type of grapples to be drawn.

If a hatched border with grapples is drawn inside a rectangle, it sits within the borders of the outer frame of the rectangle. If a hatched border with grapples is drawn outside the rectangle, it is drawn outside the boundary of the rectangle's frame. In the latter case, the function GetBoundingRect() returns a larger rectangle.

Enumerator
HandlesIn	Handles on the inside of the rectange.
HandlesOut	Handles on the outside of the rectangle.
Framed	Frame rect is drawn solid.
DashFramed	Frame rect is drawn dashed.
Grapples	Eight grapple boxes are drawn.
HatchBorder	Border handle area drawn hatched.
HatchRect	Whole rect drawn hatched.
InsideSpecial	Inside area hit-tested independently.

Definition at line 233 of file uihelper.h.

◆ TWhere

enum owl::TUIHandle::TWhere

Enumeration describing the location of a grapple selection.

These constants typically refer to the [mouse] hittest location which caused the grapples to response to a move or resize operation. The InsideSpecial designation refers to the area inside the rectangle when the hit area needs to be treated specially (for example, because it might contain text or graphics). Normally, if the area inside the rectangle is hit, it means that user wants to move the rectangle. However, if there is text inside the rectangle, the user might click on this area in order to enter text. This latter situation is referred to as an inside special case.

The hit area (Where) can be converted to a row and a column by using the following equations:

Row = Where / 3
Column = Where mod 3

The value of Where ranges from 0 (TopLeft) to 8 (BottomRight) and corresponds to the following areas of a rectangle:

You can then use these values to calculate the movement of the object and to resize the object.

Enumerator
TopLeft	Upper left corner.
TopCenter	Middle of upper edge.
TopRight	Upper right corner.
MidLeft	Middle of left edge.
MidCenter	Somewhere inside the rectangle.
MidRight	Middle of right edge.
BottomLeft	Lower left corner.
BottomCenter	Middle of lower edge.
BottomRight	Lower right corner.
Outside	Hit completely outside the object.
Inside	Hit inside object, not on handles, & InsideSpecial is set.

Definition at line 212 of file uihelper.h.

Constructor & Destructor Documentation

◆ TUIHandle()

owl::TUIHandle::TUIHandle	(	const TRect &	frame,
		uint	style = HandlesIn\|Grapples\|HatchBorder,
		int	thickness = 5 )

Constructs a TUIHandle object for the specified frame, with eight grapples drawn in a hatched border and a default thickness of 5 pixels drawn to the inside.

Definition at line 70 of file uihandle.cpp.

Member Function Documentation

◆ GetBoundingRect()

TRect owl::TUIHandle::GetBoundingRect ( ) const

Calculate the outside frame rectangle.

GetBoundingRect returns a rectangle with the size adjusted according to the thickness. For example, if the handles are outside the rectangle, GetboundingRect returns a larger rectangle. The enum TStyle defines the positions of the handles (whether the handles are defined as HandlesIn or HandlesOut).

Definition at line 116 of file uihandle.cpp.

References HandlesOut, and owl::TRect::InflatedBy().

◆ GetCursorId()

uint16 owl::TUIHandle::GetCursorId ( TWhere where )

static

Helper function to convert a where code into a cursor shape Id.

Returns the ID of a standard cursor that is appropriate for use over the location specified in the where parameter.

Definition at line 184 of file uihandle.cpp.

References Inside, and Outside.

◆ HitTest()

TUIHandle::TWhere owl::TUIHandle::HitTest ( const TPoint & point ) const

Compares a given point (point) to various parts of the rectangle.

If the hit was outside the rectangle, HitTest returns Outside. If the hatched border handle of the rectangle was hit, returns MidCenter (inside). For any other hits, HitTest returns the location of the grapple that was hit. The enum TWhere defines the possible hit areas.

Definition at line 129 of file uihandle.cpp.

References GetBoundingRect(), Grapples, Inside, InsideSpecial, MidCenter, and Outside.

◆ Move()

void owl::TUIHandle::Move	(	int	dx,
		int	dy )

Moves the rectangle relative to the values specified in dx and dy.

Definition at line 82 of file uihandle.cpp.

References owl::TRect::Offset().

◆ MoveTo()

void owl::TUIHandle::MoveTo	(	int	x,
		int	y )

Moves the rectangle to the given x and y coordinates.

Definition at line 91 of file uihandle.cpp.

References owl::TRect::Offset().

◆ Paint()

void owl::TUIHandle::Paint ( TDC & dc ) const

Paints the TUIHandle object onto the specified device context, dc.

Definition at line 202 of file uihandle.cpp.

References owl::TColor::Black, DashFramed, Framed, owl::TDC::FrameRect(), GetBoundingRect(), owl::TDC::GetROP2(), Grapples, HandlesOut, HatchBorder, HatchRect, LOCKBRUSH, owl::TDC::PatBlt(), owl::TDC::Rectangle(), owl::TDC::RestoreBrush(), owl::TDC::RestorePen(), owl::TDC::SelectObject(), owl::TDC::SelectStockObject(), owl::TDC::SetBkColor(), owl::TDC::SetROP2(), and owl::TColor::White.

◆ Size()

void owl::TUIHandle::Size	(	int	w,
		int	h )

Sets the size of the rectangle according to the measurements specified in w, the width, and h, the height.

Definition at line 101 of file uihandle.cpp.

The documentation for this class was generated from the following files:

include/owl/uihelper.h
source/owlcore/uihandle.cpp

Public Types

Public Member Functions

Static Public Member Functions