982 lines
82 KiB
HTML
982 lines
82 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - System Overview - The Interface Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
|
||
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
|
||
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheInterfaceKit_Overview.html" title="The Interface Kit" /><link rel="prev" href="TheInterfaceKit_Overview_Introduction.html" title="Introduction" /><link rel="next" href="TheInterfaceKit_Responding.html" title="Responding to the User" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheInterfaceKit_Overview_Introduction.html" title="Introduction"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheInterfaceKit_Overview.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheInterfaceKit_Responding.html" title="Responding to the User"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - System Overview - The Interface Kit</div></div><div id="headerB">Prev: <a href="TheInterfaceKit_Overview_Introduction.html">Introduction</a> Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a> Next: <a href="TheInterfaceKit_Responding.html">Responding to the User</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing"></a>Drawing</h2></div></div></div><p>
|
||
This section discusses the framework in which <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>s draw. Detailed
|
||
descriptions of the functions mentioned here can be found in the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> and <a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> class descriptions.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_View_Geometry"></a>View Geometry</h3></div></div></div><p>
|
||
Each view is assigned a coordinate system of its own. By default, the
|
||
coordinate origin—(0.0, 0.0)—is located at the left top
|
||
corner of the view rectangle. The x-axis extends to the right and the
|
||
y-axis extends downward; coordinate units count screen pixels. (For a
|
||
detailed discussion of the coordinate systems assumed by the Interface
|
||
Kit, see
|
||
"<a class="link" href="TheInterfaceKit_The_Coordinate_Space.html" title="The Coordinate Space">The Coordinate Space</a>")
|
||
</p><p>
|
||
When a view is added as a child of another view, it's located within the
|
||
coordinate system of its parent. A child is considered part of the
|
||
contents of the parent view. If the parent moves, the child moves with
|
||
it; if the parent view scrolls its contents, the child view is shifted
|
||
along with everything else in the view.
|
||
</p><p>
|
||
Since each view retains its own internal coordinate system no matter who
|
||
its parent is, where it's located within the parent, or where the parent
|
||
is located, a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
drawing and message-handling code doesn't need to
|
||
be concerned about anything exterior to itself. To do its work, a
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
need look no farther than the boundaries of its own view rectangle.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Frame_Bounds"></a>Frame and Bounds Rectangles</h4></div></div></div><p>
|
||
Although a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
doesn't have to look outside its own boundaries, it does
|
||
have to know where those boundaries are. It can get this information in
|
||
two forms:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
Since a view is located within the coordinate system of its parent,
|
||
the view rectangle is initially defined in terms of the parent's
|
||
coordinates. This defining rectangle for a view is known as its frame
|
||
rectangle. (See the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
constructor and the
|
||
<a class="link" href="BView.html#BView_Frame" title="Frame()"><code class="methodname">Frame()</code></a> function.)
|
||
</p></li><li><p>
|
||
When translated from the parent's coordinates to the internal
|
||
coordinates of the view itself, the same rectangle is known as the
|
||
bounds rectangle. (See the
|
||
<a class="link" href="BView.html#BView_Bounds" title="Bounds()"><code class="methodname">Bounds()</code></a> function.)
|
||
</p></li></ul><p>
|
||
The following illustration shows a child view 180.0 units wide and 135.0
|
||
units high. When viewed from the outside, from the perspective of its
|
||
parent's coordinate system, it has a frame rectangle with left, top,
|
||
right, and bottom coordinates at 90.0, 60.0, 270.0, and 195.0,
|
||
respectively. But when viewed from the inside, in the view's own
|
||
coordinate system, it has a bounds rectangle with coordinates at 0.0,
|
||
0.0, 180.0, and 135.0:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/frame_bounds.png" alt="Frame Bounds" /></div><p>
|
||
When a view moves to a new location in its parent, its frame rectangle
|
||
changes but not its bounds rectangle. When a view scrolls its contents,
|
||
its bounds rectangle changes, but not its frame. The frame rectangle
|
||
positions the view in the world outside; the bounds rectangle positions
|
||
the contents inside the view.
|
||
</p><p>
|
||
Since a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> does
|
||
its work in its own coordinate system, it refers to
|
||
the bounds rectangle more often than to the frame rectangle.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Nonfractional_Coordinates"></a>Nonfractional Coordinates</h4></div></div></div><p>
|
||
Because views are areas within windows and windows are displayed
|
||
on-screen, the edges of a view must line up on rows and columns of screen
|
||
pixels. It's easy to achieve this result, since coordinate units
|
||
correspond to screen pixels; one unit is the distance from the center of
|
||
a pixel to the center of an adjacent pixel. Therefore, all you must do is
|
||
define the view rectangle with nonfractional coordinates, as in the
|
||
illustration above.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Pixel_Coordinate_Dimensions"></a>Pixel and Coordinate Dimensions</h4></div></div></div><p>
|
||
It was mentioned that the child view in the illustration above is 180.0
|
||
coordinate units wide and 135.0 units high. However, this view actually
|
||
covers 181 pixel columns and 136 pixel rows on-screen.
|
||
</p><p>
|
||
Two facts conspire to determine this result. First, as stated, coordinate
|
||
units correspond to screen pixels. Second, the coordinate axes don't lie
|
||
between pixels but right in the middle of them. The x-axis splits a row
|
||
of pixels and the y-axis runs down the center of a column of pixels; the
|
||
coordinate origin where they meet is at the very center of a pixel.
|
||
Therefore, a view rectangle covers one more pixel in each direction than
|
||
its coordinate dimensions would indicate.
|
||
</p><p>
|
||
Imagine an implausibly tiny frame rectangle like the one in the following
|
||
diagram:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/tiny_frame.png" alt="Tiny Frame Rectangle" /></div><p>
|
||
Since the pixels on the edges of this 2.0 * 3.0 rectangle are treated as
|
||
being inside the rectangle, the view covers a 3 pixel * 4 pixel area.
|
||
</p><p>
|
||
This fact is important when laying out views and drawing in the bounds
|
||
rectangle (or drawing any rectangle, for that matter). However, when
|
||
discussing view coordinates and rectangles in general, it's easier and
|
||
more accurate to speak in terms of coordinate values, not
|
||
pixels—and that's the practice in this chapter. However, see
|
||
"Mapping Coordinates to Pixels"
|
||
for more on how coordinate values relate to pixels.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Scrolling"></a>Scrolling</h4></div></div></div><p>
|
||
A <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> scrolls its contents by shifting coordinate values within the
|
||
view rectangle—that is, by altering the bounds rectangle. If, for
|
||
example, the top of a view's bounds rectangle is at 100.0 and its bottom
|
||
is at 200.0, scrolling downward 50.0 units would put the top at 150.0 and
|
||
the bottom at 250.0. Contents of the view with y-coordinate values of
|
||
150.0 to 200.0, originally displayed in the bottom half of the view,
|
||
would be shifted to the top half. Contents with y-coordinate values from
|
||
200.0 to 250.0, previously unseen, would become visible at the bottom of
|
||
the view, as shown in the following illustration:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/scrolling.png" alt="Scrolling The View" /></div><p>
|
||
Scrolling doesn't move the view—it doesn't alter the frame
|
||
rectangle—it moves only what's displayed inside the view. In the
|
||
illustration above, a "data rectangle" encloses everything the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> is
|
||
capable of drawing. For example, if the view is able to display an entire
|
||
book, the data rectangle would be large enough to enclose all the lines
|
||
and pages of the book laid end to end. However, since a
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> can draw
|
||
only within its bounds rectangle, everything in the data rectangle with
|
||
coordinates that fall outside the bounds rectangle would be invisible. To
|
||
make unseen data visible, the bounds rectangle must change the
|
||
coordinates that it encompasses. Scrolling can be thought of as sliding
|
||
the view's bounds rectangle to a new position on its data rectangle, as
|
||
is shown in the illustration above. However, as it appears to the user,
|
||
it's moving the data rectangle under the bounds rectangle. The view
|
||
doesn't move; the data does.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Clipping_Region"></a>The Clipping Region</h4></div></div></div><p>
|
||
The Application Server clips the images that a
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> produces to the
|
||
region where it's permitted to draw.
|
||
</p><p>
|
||
This region is never any larger than the view's bounds rectangle; a view
|
||
cannot draw outside its bounds. Furthermore, since a child is considered
|
||
part of its parent, a view can't draw outside the bounds rectangle of its
|
||
parent either—or, for that matter, outside the bounds rectangle of
|
||
any ancestor view. In addition, since child views draw after, and
|
||
therefore logically in front of, their parents, a view concedes some of
|
||
its territory to its children.
|
||
</p><p>
|
||
Thus, the visible region of a view is the part of its bounds rectangle
|
||
that's inside the bounds rectangles of all its ancestors, minus the frame
|
||
rectangles of its children. This is illustrated in the following figure.
|
||
It shows a hierarchy of three views—X, Y, and Z. The area filled
|
||
with a crosshatch pattern is the visible region of view X; it omits the
|
||
area occupied by its child, view Y. The visible region of view Y is
|
||
colored dark gray; it omits the part of the view that lies outside its
|
||
parent. View Z has no visible region, for it lies outside the bounds
|
||
rectangle of its ancestor, view X:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/drawing4.png" alt="View Clipping Outside The Parent" /></div><p>
|
||
The visible region of a view might be further restricted if its window is
|
||
obscured by another window or if the window it's in lies partially
|
||
off-screen. The visible region includes only those areas that are
|
||
actually visible to the user. For example, if the three views in the
|
||
previous illustration were in a window that was partially blocked by
|
||
another window, their visible regions might be considerably smaller. This
|
||
is shown in the next figure:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/drawing5.png" alt="Clipping Areas For Covered Windows" /></div><p>
|
||
Note that in this case, view X has a discontinuous visible region.
|
||
</p><p>
|
||
The Application Server clips the drawing that a view does to a region
|
||
that's never any larger than the visible region. On occasion, it may be
|
||
smaller. For the sake of efficiency, while a view is being automatically
|
||
updated, the clipping region excludes portions of the visible region that
|
||
don't need to be redrawn:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
When a view is scrolled, the Application Server may be able to shift
|
||
some of its contents from one portion of the visible region to another.
|
||
The clipping region excludes any part of the visible region that the
|
||
server was able to update on its own; it includes only the part where
|
||
the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> must produce images that were not previously visible.
|
||
</p></li><li><p>
|
||
If a view is resized larger, the clipping region may include only the
|
||
new areas that were added to the visible region. (But see the flags
|
||
argument for the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> constructor.)
|
||
</p></li><li><p>
|
||
If only part of a view is invalidated (by the
|
||
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">Invalidate()</code></a> function),
|
||
the clipping region is the intersection of the visible region and the
|
||
invalid rectangle.
|
||
</p></li></ul><p>
|
||
An application can also limit the clipping region for a view by passing a
|
||
<a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a>
|
||
object to
|
||
<a class="link" href="BView.html#BView_ConstrainClippingRegion" title="ConstrainClippingRegion()"><code class="methodname">ConstrainClippingRegion()</code></a>.
|
||
The clipping region won't
|
||
include any areas that aren't in the region passed. The Application
|
||
Server calculates the clipping region as it normally would but intersects
|
||
it with the specified region.
|
||
</p><p>
|
||
You can obtain the current clipping region for a view by calling
|
||
<a class="link" href="BView.html#BView_GetClippingRegion" title="GetClippingRegion()"><code class="methodname">GetClippingRegion()</code></a>.
|
||
(See also the <a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> class description.)
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_View_Color"></a>The View Color</h4></div></div></div><p>
|
||
Every view has a basic, underlying color. It's the color that fills the
|
||
view rectangle before the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> does any drawing. The Application Server
|
||
paints the view with this color before any view-specific drawing
|
||
functions are called. The user may catch a glimpse of the color when the
|
||
view is first shown on-screen, when it's resized larger, and when it's
|
||
erased in preparation for an update. It will also be seen wherever the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> fails to draw in the visible region.
|
||
</p><p>
|
||
In a sense, the view color is the canvas on which the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> draws. It
|
||
doesn't enter into any of the object's drawing operations except to
|
||
provide a background. Although it's one of the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s graphics
|
||
parameters, it's not one that any drawing functions refer to.
|
||
</p><p>
|
||
The default view color is white. You can assign a different color to a
|
||
view by calling <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
<a class="link" href="BView.html#BView_SetViewColor" title="SetViewColor(), ViewColor()"><code class="methodname">SetViewColor()</code></a> function. If you set the view
|
||
color to <code class="constant">B_TRANSPARENT_COLOR</code>, the Application Server won't erase the
|
||
view's clipping region before an update. This is appropriate only if the
|
||
view erases itself by touching every pixel in the clipping region when it
|
||
draws.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_BackgroundBitmap"></a>The Background Bitmap</h4></div></div></div><p>
|
||
Every view may additionally have a background bitmap. The Application
|
||
Server draws this bitmap after it fills in the view color and before any
|
||
view-specific drawing functions are called. The view color will be
|
||
visible in regions the background bitmap doesn't cover.
|
||
</p><p>
|
||
A view begins life without a background bitmap. A background bitmap may
|
||
be added with <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
<a class="link" href="BView.html#BView_SetViewBitmap" title="SetViewBitmap(), ClearViewBitmap()"><code class="methodname">SetViewBitmap()</code></a>
|
||
function and subsequently removed with
|
||
<a class="link" href="BView.html#BView_ClearViewBitmap"><code class="methodname">ClearViewBitmap()</code></a>.
|
||
</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mechanics_Drawing"></a>The Mechanics of Drawing</h3></div></div></div><p>
|
||
Views draw through the following set of primitive functions:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
<a class="link" href="BView.html#BView_DrawString" title="DrawString()"><code class="methodname">DrawString()</code></a>
|
||
draws a string of characters.
|
||
<a class="link" href="BView.html#BView_DrawChar" title="DrawChar()"><code class="methodname">DrawChar()</code></a>
|
||
is a variant of this function; it draws just a single character.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_DrawPicture" title="DrawPicture(), DrawPictureAsync()"><code class="methodname">DrawPicture()</code></a>
|
||
executes a set of recorded drawing instructions.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_DrawBitmap" title="DrawBitmap(), DrawBitmapAsync()"><code class="methodname">DrawBitmap()</code></a>
|
||
produces an image from a bitmap.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_DrawBitmap" title="DrawBitmap(), DrawBitmapAsync()"><code class="methodname">DrawBitmap()</code></a>CopyBits()
|
||
copies an image from one location to another.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_FillEllipse"><code class="methodname">FillEllipse()</code></a>,
|
||
<a class="link" href="BView.html#BView_FillRegion" title="FillRegion()"><code class="methodname">FillRegion()</code></a>,
|
||
and other <code class="methodname">Fill…()</code> functions fill closed shapes.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_StrokeLine" title="StrokeLine()"><code class="methodname">StrokeLine()</code></a>,
|
||
<a class="link" href="BView.html#BView_StrokeArc"><code class="methodname">StrokeArc()</code></a>,
|
||
and other <code class="methodname">Stroke…()</code> functions stroke
|
||
lines along defined paths.
|
||
</p></li><li><p>
|
||
<a class="link" href="BView.html#BView_BeginLineArray" title="BeginLineArray(), AddLine(), EndLineArray()"><code class="methodname">BeginLineArray()</code></a>,
|
||
<a class="link" href="BView.html#BView_AddLine"><code class="methodname">AddLine()</code></a>, and
|
||
<a class="link" href="BView.html#BView_EndLineArray"><code class="methodname">EndLineArray()</code></a> draw a set of
|
||
straight lines, all of the same width, but possibly in different colors.
|
||
</p></li></ul><p>
|
||
The way these functions work depends not only on the values that they're
|
||
passed—the particular string, bitmap, arc, or ellipse that's to be
|
||
drawn—but on previously set values in the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s graphics
|
||
environment.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Graphics_Environment"></a>Graphics Environment</h4></div></div></div><p>
|
||
Each <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
object maintains its own graphics environment for drawing. The
|
||
view color, coordinate system, and clipping region are fundamental parts
|
||
of that environment, but not the only parts. It also includes a number of
|
||
parameters that can be set and reset at will to affect the next image
|
||
drawn. These parameters are:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
Font attributes that determine the appearance of text the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
draws. (See
|
||
<a class="link" href="BView.html#BView_SetFont" title="SetFont(), GetFont()"><code class="methodname">SetFont()</code></a> and the
|
||
<a class="link" href="BFont.html" title="BFont"><code class="classname">BFont</code></a> class.)
|
||
</p></li><li><p>
|
||
Two pen parameters—a location and a size. The pen location
|
||
determines where the next drawing will occur, and the pen size
|
||
determines the thickness of stroked lines. (See
|
||
<a class="link" href="BView.html#BView_MovePenBy" title="MovePenBy(), MovePenTo(), PenLocation()"><code class="methodname">MovePenBy()</code></a> and
|
||
<a class="link" href="BView.html#BView_SetPenSize" title="SetPenSize(), PenSize()"><code class="methodname">SetPenSize()</code></a>.)
|
||
</p></li><li><p>
|
||
Two current colors—a high color and a low color—that can
|
||
be used either alone or in combination to form a pattern or halftone.
|
||
The high color is used for most drawing. The low color is sometimes set
|
||
to the underlying view color so that it can be used to erase other
|
||
drawing or, because it matches the view background, make it appear that
|
||
drawing has not touched certain pixels.
|
||
</p><p>
|
||
(The high and low colors roughly match what other systems call the
|
||
fore and back, or foreground and background, colors. However, neither
|
||
color truly represents the color of the foreground or background. The
|
||
terminology high and low is meant to keep the sense of two opposing
|
||
colors and to match how they're defined in a pattern. A pattern bit is
|
||
turned on for the high color and turned off for the low color. See the
|
||
<a class="link" href="BView.html#BView_SetHighColor" title="SetHighColor(), HighColor() , SetLowColor() , LowColor()"><code class="methodname">SetHighColor()</code></a> and
|
||
<a class="link" href="BView.html#BView_SetLowColor"><code class="methodname">SetLowColor()</code></a> functions in the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> class
|
||
description and the
|
||
"<a class="link" href="TheInterfaceKit_Drawing.html#TheInterfaceKit_Drawing_Patterns" title="Patterns">Patterns</a>"
|
||
section.
|
||
</p></li><li><p>
|
||
A drawing mode that determines how the next image is to be rendered.
|
||
(See
|
||
"<a class="link" href="TheInterfaceKit_Drawing.html#TheInterfaceKit_Drawing_Drawing_Modes" title="Drawing Modes">Drawing Modes</a>" and the
|
||
<a class="link" href="BView.html#BView_SetDrawingMode" title="SetDrawingMode(), DrawingMode()"><code class="methodname">SetDrawingMode()</code></a>
|
||
function.)
|
||
</p></li></ul><p>
|
||
By default, a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
graphics parameters are set to the following values:
|
||
</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><tbody><tr><td>Font</td><td>The system plain font (be_plain_font)</td></tr><tr><td>Pen position</td><td>(0.0, 0.0)</td></tr><tr><td>Pen size</td><td>1.0 coordinate units</td></tr><tr><td>High color</td><td>Black (red, green, and blue components all equal to 0)</td></tr><tr><td>Low color</td><td>White (red, green, and blue components all equal to 255)</td></tr><tr><td>Drawing mode</td><td>Copy mode (<code class="constant">B_OP_COPY</code>)</td></tr><tr><td>View color</td><td>White (red, green, and blue components all equal to 255)</td></tr><tr><td>Clipping region</td><td>The visible region of the view</td></tr><tr><td>Coordinate system</td><td>Origin at the left top corner of the bounds rectangle</td></tr></tbody></table></div><p>
|
||
However, as
|
||
"<a class="link" href="TheInterfaceKit_Drawing.html#TheInterfaceKit_Drawing_Views_Server" title="Views and the Server">Views and the Server</a>"
|
||
explains, these values have meaning only when the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> is assigned to a window.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Pen"></a>The Pen</h4></div></div></div><p>
|
||
The pen is a fiction that encompasses two properties of a view's graphics
|
||
environment: the current drawing location and the thickness of stroked
|
||
lines.
|
||
</p><p>
|
||
The pen location determines where the next image will be drawn—but
|
||
only if another location isn't explicitly passed to the drawing function.
|
||
Some drawing functions alter the pen location—as if the pen
|
||
actually moves as it does the drawing—but usually it's set by
|
||
calling <a class="link" href="BView.html#BView_MovePenBy" title="MovePenBy(), MovePenTo(), PenLocation()"><code class="methodname">MovePenBy()</code></a>
|
||
or
|
||
<a class="link" href="BView.html#BView_MovePenTo"><code class="methodname">MovePenTo()</code></a>.
|
||
</p><p>
|
||
The pen that draws lines (through the various <code class="methodname">Stroke…()</code> functions) has
|
||
a malleable tip that can be made broader or narrower by calling the
|
||
calling <a class="link" href="BView.html#BView_SetPenSize" title="SetPenSize(), PenSize()"><code class="methodname">SetPenSize()</code></a>
|
||
function. The larger the pen size, the thicker the line that
|
||
it draws.
|
||
</p><p>
|
||
The pen size is expressed in coordinate units, which must be translated
|
||
to a particular number of pixels for the display device. This is done by
|
||
scaling the pen size to a device-specific value and rounding to the
|
||
closest integer. For example, pen sizes of 2.6 and 3.3 would both
|
||
translate to 3 pixels on-screen, but to 7 and 10 pixels respectively on a
|
||
300dpi printer.
|
||
</p><p>
|
||
The size is never rounded to 0; no matter how small the pen may be, the
|
||
line never disappears. If the pen size is set to 0.0, the line will be as
|
||
thin as possible—it will be drawn using the fewest possible pixels
|
||
on the display device. (In other words, it will be rounded to 1 for all
|
||
devices.)
|
||
</p><p>
|
||
If the pen size translates to a tip that's broader than 1 pixel, the line
|
||
is drawn with the tip centered on the path of the line. Roughly the same
|
||
number of pixels are colored on both sides of the path.
|
||
</p><p>
|
||
A later section,
|
||
"<a class="link" href="TheInterfaceKit_The_Coordinate_Space.html#TheInterfaceKit_The_Coordinate_Space_Picking_Pixels" title="Picking Pixels to Stroke and Fill">Picking Pixels to Stroke and Fill</a>",
|
||
illustrates how pens of different sizes choose the pixels to be colored.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Colors"></a>Colors</h4></div></div></div><p>
|
||
The high and low colors are specified as rgb_color values—full
|
||
32-bit values with separate red, green, and blue color components, plus
|
||
an alpha component for transparency. Although there may sometimes be
|
||
limitations on the colors that can be rendered on-screen, there are no
|
||
restrictions on the colors that can be specified.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Color_Spaces"></a>Color Spaces</h4></div></div></div><p>
|
||
The way colors are specified for a bitmap depends on the color space in
|
||
which they're interpreted. The color space determines the depth of the
|
||
bitmap data (how many bits of information are stored for each pixel), the
|
||
interpretation of the data (whether it represents shades of gray or true
|
||
colors, whether it's segmented into color components, what the components
|
||
are, and so on), and the arrangement of components within the data
|
||
(whether big-endian or little-endian). These six basic color spaces are
|
||
recognized:
|
||
</p><table class="variablelist"><tbody><tr><td><p><span class="term"><code class="constant">B_GRAY1</code></span></p></td><td><p>One bit of data per pixel, where 1 is black and 0 is white.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_GRAY8</code></span></p></td><td><p>Eight bits of data per pixel, where a value of 255 is black and 0
|
||
is white.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_CMAP8</code></span></p></td><td><p>Eight bits of data per pixel, interpreted as an index into a list
|
||
of 256 colors. The list is part of the system color map and is the same
|
||
for all applications.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_RGB15</code></span></p></td><td><p>Three components of data per pixel—blue, green, and red, in
|
||
that order—with 5 bits each for red, green, and blue. The first bit
|
||
of the pixel data is not associated with any color component.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_RGBA15</code></span></p></td><td><p>Four components of data per pixel—blue, green, red, and
|
||
alpha, in that order—with 5 bits each for red, green, and blue, and
|
||
1 bit for alpha.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_RGB16</code></span></p></td><td><p>Three components of data per pixel—blue, green, and red, in
|
||
that order—with 5 bits each for red and blue, and 6 bits for green.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_RGB32</code></span></p></td><td><p>Four components of data per pixel—blue, green, red, and
|
||
alpha, in that order—with 8 bits per component. A component value
|
||
of 255 yields the maximum amount of red, green, or blue, and a value of 0
|
||
indicates the absence of that color.</p></td></tr></tbody></table><p>
|
||
The components in the <code class="constant">B_RGB32</code>, <code class="constant">B_RGB16</code>,
|
||
and <code class="constant">B_RGB15</code> color spaces are
|
||
meshed rather than separated into distinct planes; all four components
|
||
are specified for the first pixel before the four components for the
|
||
second pixel, and so on. The order of bytes for these two types is
|
||
little-endian, which means that for <code class="constant">B_RGB32</code> data, the component bytes
|
||
appear in the order blue, green, red, and alpha.
|
||
</p><p>
|
||
Counterpart color spaces are defined for big-endian data. <code class="constant">B_RGB32_BIG</code>,
|
||
<code class="constant">B_RGBA16_BIG</code>, <code class="constant">B_RGBA15_BIG</code>, and
|
||
<code class="constant">B_RGB15</code>_BIG, are equivalent to <code class="constant">B_RGB32</code>,
|
||
<code class="constant">B_RGB16</code>, <code class="constant">B_RGBA15</code>,
|
||
and <code class="constant">B_RGB15</code>—except for the order of bytes. The
|
||
Be operating system retains data in the little-endian formats; the
|
||
big-endian color spaces are defined only to label noncompatible data that
|
||
the system must convert and to allow drivers to communicate precise
|
||
formats to the operating system.
|
||
</p><p>
|
||
Alpha should be 0 for 100% transparent, or 255 (for 8-bit alpha channels)
|
||
for 100% opaque. For 1-bit alpha channels, a value of 1 indicates opaque.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_The_Screen"></a>The Screen</h4></div></div></div><p>
|
||
The screen can be configured to display colors in either the <code class="constant">B_CMAP8</code>,
|
||
<code class="constant">B_RGB15</code>, or <code class="constant">B_RGB32</code> color spaces.
|
||
When it's in the <code class="constant">B_CMAP8</code> or <code class="constant">B_RGB15</code>
|
||
color spaces, specified <span class="type">rgb_color</span>s are displayed as the closest available
|
||
color. (See the
|
||
<a class="link" href="BBitmap.html" title="BBitmap"><code class="classname">BBitmap</code></a> and
|
||
<a class="link" href="BScreen.html" title="BScreen"><code class="classname">BScreen</code></a> classes.)
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Patterns"></a>Patterns</h4></div></div></div><p>
|
||
Most functions that stroke a line or fill a closed shape don't draw
|
||
directly in either the high or the low color. Rather they take a pattern,
|
||
an arrangement of one or both colors that's repeated over the entire
|
||
surface being drawn. A pattern might consist of just the high color, just
|
||
the low color, or some combination of the two.
|
||
</p><p>
|
||
By combining the low color with the high color, patterns can produce
|
||
dithered colors that lie somewhere between two hues in the <code class="constant">B_CMAP8</code> color
|
||
space. Patterns also permit drawing with less than the solid high color
|
||
(for intermittent or broken lines, for example) and can take advantage of
|
||
drawing modes that treat the low color as if it were transparent, as
|
||
discussed in the next section.
|
||
</p><p>
|
||
A pattern is defined as an 8-pixel by 8-pixel square. The <span class="type">pattern</span> type is
|
||
8 bytes long, with 1 byte per row and 1 bit per pixel. Rows are specified
|
||
from top to bottom and pixels from left to right. Bits marked 1 designate
|
||
the high color; those marked 0 designate the low color. For example, a
|
||
pattern of wide diagonal stripes could be defined as follows:
|
||
</p><pre class="programlisting example cpp"><span class="type">pattern</span> <code class="varname">stripes</code> = { 0xc7, 0x8f, 0x1f, 0x3e,
|
||
0x7c, 0xf8, 0xf1, 0xe3 };</pre><p>
|
||
Patterns repeat themselves across the screen, like tiles laid side by
|
||
side. The pattern defined above looks like this:
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/fill_pattern.png" alt="Fill Patterns" /></div><p>
|
||
The dotted lines in this illustration show the separation of the screen
|
||
into pixels. The thicker black line outlines one 8 * 8 square that the
|
||
pattern defines.
|
||
</p><p>
|
||
The outline of the shape being filled or the width of the line being
|
||
stroked determines where the pattern is revealed. It's as if the screen
|
||
was covered with the pattern just below the surface, and stroking or
|
||
filling allowed some of it to show through. For example, stroking a
|
||
1-pixel wide horizontal path in the pattern illustrated above would
|
||
result in a dotted line, with the dashes (in the high color) slightly
|
||
longer than the spaces between (in the low color):
|
||
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/line_pattern.png" alt="Line Patterns" /></div><p>
|
||
When stroking a line or filling a shape, the pattern serves as the source
|
||
image for the current drawing mode, as explained in
|
||
"<a class="link" href="TheInterfaceKit_Drawing.html#TheInterfaceKit_Drawing_Drawing_Modes" title="Drawing Modes">Drawing Modes</a>"
|
||
next. The nature of the mode determines how the pattern interacts with the
|
||
destination image, the image already in place.
|
||
</p><p>
|
||
The Interface Kit defines three patterns:
|
||
</p><table class="variablelist"><tbody><tr><td><p><span class="term"><code class="constant">B_SOLID_HIGH</code></span></p></td><td><p>Consists only of the high color.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_SOLID_LOW</code></span></p></td><td><p>Has only the low color.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MIXED_COLORS</code></span></p></td><td><p>Mixes the two colors evenly, like the pattern on a
|
||
checkerboard.</p></td></tr></tbody></table><p>
|
||
<code class="constant">B_SOLID_HIGH</code> is the default pattern for all drawing functions.
|
||
Applications can define as many other patterns as they need.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Drawing_Modes"></a>Drawing Modes</h4></div></div></div><p>
|
||
When a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> draws, it in effect transfers an image to a target location
|
||
somewhere in the view rectangle. The drawing mode determines how the
|
||
image being transferred interacts with the image already in place at that
|
||
location. The image being transferred is known as the source image; it
|
||
might be a bitmap or a pattern of some kind. The image already in place
|
||
is known as the destination image.
|
||
</p><p>
|
||
In the simplest and most straightforward kind of drawing, the source
|
||
image is simply painted over the destination; the source replaces the
|
||
destination. However, there are other possibilities. There are ten
|
||
different drawing modes—ten distinct ways of combining the source
|
||
and destination images. The modes are designated by <span class="type">drawing_mode</span>
|
||
constants that can be passed to
|
||
<a class="link" href="BView.html#BView_SetDrawingMode" title="SetDrawingMode(), DrawingMode()"><code class="methodname">SetDrawingMode()</code></a>:
|
||
</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><tbody><tr><td><code class="constant">B_OP_COPY</code></td><td><code class="constant">B_OP_ADD</code></td></tr><tr><td><code class="constant">B_OP_OVER</code></td><td><code class="constant">B_OP_SUBTRACT</code></td></tr><tr><td><code class="constant">B_OP_ERASE</code></td><td><code class="constant">B_OP_BLEND</code></td></tr><tr><td><code class="constant">B_OP_INVERT</code></td><td><code class="constant">B_OP_MIN</code></td></tr><tr><td><code class="constant">B_OP_SELECT</code></td><td><code class="constant">B_OP_MAX</code></td></tr></tbody></table></div><p>
|
||
<code class="constant">B_OP_COPY</code> is the default mode and the simplest. It transfers the source
|
||
image to the destination, replacing whatever was there before. The
|
||
destination is ignored.
|
||
</p><p>
|
||
In the other modes, however, some of the destination might be preserved,
|
||
or the source and destination might be combined to form a result that's
|
||
different from either of them. For these modes, it's convenient to think
|
||
of the source image as an image that exists somewhere independent of the
|
||
destination location, even though it's not actually visible. It's the
|
||
image that would be rendered at the destination in <code class="constant">B_OP_COPY</code> mode.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Bitmaps_Patterns"></a>Bitmaps and Patterns</h4></div></div></div><p>
|
||
The modes work for all <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> drawing functions—including those that
|
||
stroke lines and fill shapes, those that draw characters, and those that
|
||
image bitmaps. The way they work depends foremost on the nature of the
|
||
source image—whether it's a pattern or a bitmap. For the <code class="methodname">Fill…()</code>
|
||
and <code class="methodname">Stroke…()</code> functions, the source image is a pattern that has the
|
||
same shape as the area being filled or the area the pen touches as it
|
||
strokes a line. For
|
||
<a class="link" href="BView.html#BView_DrawBitmap" title="DrawBitmap(), DrawBitmapAsync()"><code class="methodname">DrawBitmap()</code></a>,
|
||
the source image is a rectangular bitmap.
|
||
</p><p>
|
||
In a sense, a pattern is simply a bitmap that's one bit deep. It's a
|
||
bitmap consisting of two colors, one which maps to the current high color
|
||
and another that maps to the current low color. As we shall see later, a
|
||
<code class="constant">B_MONOCHROME_1_BIT</code> bitmap acts just like a pattern. However, patterns and
|
||
bitmaps generally behave differently:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
Only a source pattern has designated high and low colors. Even if a
|
||
source bitmap has colors that match the current high and low colors,
|
||
they're not handled like the colors in a pattern; they're treated just
|
||
like any other color in the bitmap.
|
||
</p></li><li><p>
|
||
On the other hand, only a source bitmap can have transparent pixels.
|
||
In the <code class="constant">B_CMAP8</code> color space, a pixel is made transparent by assigning it
|
||
the <code class="constant">B_TRANSPARENT_MAGIC_CMAP8</code> value. In the <code class="constant">B_RGB32</code> color space, a
|
||
pixel assigned the <code class="constant">B_TRANSPARENT_MAGIC_RGBA32</code> value is considered
|
||
transparent. These values have meaning only for source bitmaps, not for
|
||
source patterns. If the current high or low color in a pattern happens
|
||
to have a transparent value, it's still treated as the high or low
|
||
color, not like transparency in a bitmap. For big endian color spaces,
|
||
the transparency color should be byte-swapped from its little endian
|
||
counterpart.
|
||
</p></li></ul><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><tbody><tr><td><code class="constant">B_TRANSPARENT_MAGIC_CMAP8</code></td><td>8-bit indexed color transparent pixel.</td></tr><tr><td><code class="constant">B_TRANSPARENT_MAGIC_RGBA15</code></td><td>15-bit transparent pixel.</td></tr><tr><td><code class="constant">B_TRANSPARENT_MAGIC_RGBA15_BIG</code></td><td>15-bit transparent pixel, big-endian.</td></tr><tr><td><code class="constant">B_TRANSPARENT_MAGIC_RGBA32</code></td><td>32-bit transparent pixel.</td></tr><tr><td><code class="constant">B_TRANSPARENT_MAGIC_RGBA32_BIG</code></td><td>32-bit transparent pixel, big-endian.</td></tr></tbody></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Drawing_Modes_Color_Spaces"></a>Drawing Modes and Color Spaces</h4></div></div></div><p>
|
||
The way the drawing modes work also depends on the color space of the
|
||
source image and the color space of the destination. The following
|
||
discussion concentrates on drawing where the source and destination both
|
||
contain colors. This is the most common case, and also the one that's
|
||
most general.
|
||
</p><p>
|
||
The source and destination images can have different color spaces. For
|
||
example, a source bitmap might be defined in the <code class="constant">B_CMAP8</code> space while the
|
||
destination is displayed in the full color <code class="constant">B_RGB32</code> color space. The
|
||
drawing operation merely combines the colors in the two images in some
|
||
way. It doesn't transfer the color space of the source image to the
|
||
destination. The image that results from the drawing operation will
|
||
always be in the color space of the destination image.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mode_Definitions"></a>Mode Definitions</h4></div></div></div><p>
|
||
When applied to colors, the ten drawing modes fall naturally into four
|
||
groups:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The <code class="constant">B_OP_COPY</code> mode, which copies the source image to the destination.
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_OVER</code>, <code class="constant">B_OP_ERASE</code>,
|
||
<code class="constant">B_OP_INVERT</code>, and <code class="constant">B_OP_SELECT</code> modes,
|
||
which—despite their differences—all treat the low color in
|
||
a pattern as if it were transparent.
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_ADD</code>, <code class="constant">B_OP_SUBTRACT</code>, and
|
||
<code class="constant">B_OP_BLEND</code> modes, which combine
|
||
colors in the source and destination images.
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_MIN</code> and <code class="constant">B_OP_MAX</code> modes,
|
||
which choose between the source and destination colors.
|
||
</p></li></ul><p>
|
||
The following paragraphs describe each of these groups in turn.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mode_Definitions_Copy"></a>Copy Mode</h5></div></div></div><p>
|
||
In <code class="constant">B_OP_COPY</code> mode, the source image replaces the destination. This is the
|
||
default drawing mode and the one most commonly used. Because this mode
|
||
doesn't have to test for particular color values in the source image,
|
||
look at the colors in the destination, or compute colors in the result,
|
||
it's also the fastest of the modes.
|
||
</p><p>
|
||
If the source image contains transparent pixels, their transparency will
|
||
be retained in the result; the transparent value is copied just like any
|
||
other color. However, the appearance of a transparent pixel when shown
|
||
on-screen is indeterminate. If a source image has transparent portions,
|
||
it's best to transfer it to the screen in <code class="constant">B_OP_OVER</code> or another mode. In
|
||
all modes other than <code class="constant">B_OP_COPY</code>, a transparent pixel in a source bitmap
|
||
preserves the color of the corresponding destination pixel.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mode_Definitions_Transparency"></a>Transparency Modes</h5></div></div></div><p>
|
||
Four drawing modes—<code class="constant">B_OP_OVER</code>,
|
||
<code class="constant">B_OP_ERASE</code>, <code class="constant">B_OP_INVERT</code>, and
|
||
<code class="constant">B_OP_SELECT</code>—are designed specifically to make use of transparency
|
||
in the source image; they're able to preserve some of the destination
|
||
image. In these modes (and only these modes) the low color in a source
|
||
pattern acts just like transparency in a source bitmap.
|
||
</p><p>
|
||
Each of these modes has a different effect on the destination
|
||
image—but only in those places where the source image is not
|
||
transparent. One of the modes, <code class="constant">B_OP_OVER</code>, transfers some of the source
|
||
image to the destination. The other three modes play with the destination
|
||
in some way—erase it, invert it, or select colors in
|
||
it—without regard to the source image. For these modes, the only
|
||
thing that matters about the source image is where it's transparent and
|
||
where it's not. Each of the four modes is described below:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The <code class="constant">B_OP_OVER</code> mode places the source image "over" the destination;
|
||
the source provides the foreground and the destination the background.
|
||
In this mode, the source image replaces the destination image (just as
|
||
in the <code class="constant">B_OP_COPY</code> mode)—except where a source bitmap has
|
||
transparent pixels and a source pattern has the low color. Transparency
|
||
in a bitmap and the low color in a pattern retain the destination image
|
||
in the result.
|
||
</p></li><li><p>
|
||
By masking out the unwanted parts of a rectangular bitmap with
|
||
transparent pixels, this mode can place an irregularly shaped source
|
||
image in front of a background image. Transparency in the source
|
||
foreground lets the destination background show through. The
|
||
versatility of <code class="constant">B_OP_OVER</code> makes it the second most commonly used mode,
|
||
after <code class="constant">B_OP_COPY</code>.
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_ERASE</code> mode doesn't draw the source image at all. Instead, it
|
||
erases the destination image. Like <code class="constant">B_OP_OVER</code>, it preserves the
|
||
destination image wherever a source bitmap is transparent or a source
|
||
pattern has the low color. But everywhere else—where the source
|
||
bitmap isn't transparent and the source pattern has the high
|
||
color—it removes the destination image, replacing it with the low
|
||
color.
|
||
</p><p>
|
||
Although this mode can be used for selective erasing, it's simpler to
|
||
erase by filling an area with the B_SOLID_LOW pattern in <code class="constant">B_OP_COPY</code> mode.
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_INVERT</code> mode, like <code class="constant">B_OP_ERASE</code>, doesn't draw the source image.
|
||
Instead, it inverts the colors in the destination image. As in the case
|
||
of the <code class="constant">B_OP_OVER</code> and <code class="constant">B_OP_ERASE</code> modes, where a source bitmap is
|
||
transparent or a source pattern has the low color, the destination
|
||
image remains unchanged in the result. Everywhere else, the color of
|
||
the destination image is inverted.
|
||
</p><p>
|
||
The inversion of an rgb_color is the complement of its color
|
||
components. For example, the inversion of a red value of 58 would be
|
||
197 (255 - 58).
|
||
</p></li><li><p>
|
||
The <code class="constant">B_OP_SELECT</code> mode also doesn't draw the source image. It replaces
|
||
the high color in the destination image with the low color and the low
|
||
color with the high color. As for the other modes in this group, where
|
||
a source bitmap is transparent or a source pattern has the low color,
|
||
the destination image remains unchanged in the result. Everywhere else,
|
||
the high and low colors are switched.
|
||
</p><p>
|
||
This is similar to the <code class="constant">B_OP_INVERT</code> mode, except that <code class="constant">B_OP_SELECT</code>
|
||
affects at most only two colors in the destination image. The
|
||
destination is preserved not only where the source is transparent, but
|
||
also where its colors don't match the current high and low colors.
|
||
</p></li></ul><p>
|
||
These four modes also work for monochrome images. If the source image is
|
||
monochrome, the distinction between source bitmaps and source patterns
|
||
breaks down. Two rules apply:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
If the source image is a monochrome bitmap, it acts just like a
|
||
pattern. A value of 1 in the bitmap designates the current high color,
|
||
and a value of 0 designates the current low color. Thus, 0, rather than
|
||
<code class="constant">B_TRANSPARENT_MAGIC_*</code>, becomes the transparent value.
|
||
</p></li><li><p>
|
||
If the source and destination are both monochrome, the high color is
|
||
necessarily black (1), and the low color is necessarily white
|
||
(0)—but otherwise the drawing modes work as described. With the
|
||
possible colors this severely restricted, the three modes are reduced
|
||
to boolean operations: <code class="constant">B_OP_OVER</code> is the same as a logical OR,
|
||
<code class="constant">B_OP_INVERT</code> and <code class="constant">B_OP_SELECT</code>
|
||
are the same as logical exclusive OR, and
|
||
<code class="constant">B_OP_ERASE</code> is the same as an inversion of logical AND.
|
||
</p></li></ul></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mode_Definitions_Blending"></a>Blending Modes</h5></div></div></div><p>
|
||
Three drawing modes—<code class="constant">B_OP_ADD</code>, <code class="constant">B_OP_SUBTRACT</code>, and
|
||
<code class="constant">B_OP_BLEND</code>—combine the source and destination images, pixel by
|
||
pixel, and color component by color component. As in most of the other
|
||
modes, transparency in a source bitmap preserves the destination image in
|
||
the result. Elsewhere, the result is a combination of the source and
|
||
destination. The high and low colors of a source pattern aren't treated
|
||
in any special way; they're handled just like other colors.
|
||
</p><ul class="itemizedlist"><li><p>
|
||
<code class="constant">B_OP_ADD</code> adds each component of the source color to the corresponding
|
||
component of the destination color, with a component value of 255 as
|
||
the limit. Colors become brighter, closer to white.
|
||
</p><p>
|
||
By adding a uniform gray to each pixel in the destination, for
|
||
example, the whole destination image can be brightened by a constant
|
||
amount.
|
||
</p></li><li><p>
|
||
<code class="constant">B_OP_SUBTRACT</code> subtracts each component of the source color from the
|
||
corresponding component of the destination color, with a component
|
||
value of 0 as the limit. Colors become darker, closer to black.
|
||
</p><p>
|
||
For example, by subtracting a uniform amount from the red component
|
||
of each pixel in the destination, the whole image can be made less red.
|
||
</p></li><li><p>
|
||
<code class="constant">B_OP_BLEND</code> averages each component of the source and destination
|
||
colors (adds the source and destination components and divides by 2).
|
||
The two images are merged into one.
|
||
</p></li></ul><p>
|
||
These modes work only for color images, not for monochrome ones. If the
|
||
source or destination is specified in the <code class="constant">B_CMAP8</code> color space, the color
|
||
will be expanded to a full <code class="constant">B_RGB32</code> value to compute the result; the
|
||
result is then contracted to the closest color in the <code class="constant">B_CMAP8</code> color space.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Mode_Definitions_Selection"></a>Selection Modes</h5></div></div></div><p>
|
||
Two drawing modes—<code class="constant">B_OP_MAX</code> and <code class="constant">B_OP_MIN</code>—compare each pixel in
|
||
the source image to the corresponding pixel in the destination image and
|
||
select one to keep in the result. If the source pixel is transparent,
|
||
both modes select the destination pixel. Otherwise, <code class="constant">B_OP_MIN</code> selects the
|
||
darker of the two colors and <code class="constant">B_OP_MAX</code> selects the brighter of the two. If
|
||
the source image is a uniform shade of gray, for example, <code class="constant">B_OP_MAX</code> would
|
||
substitute that shade for every pixel in the destination image that was
|
||
darker than the gray.
|
||
</p><p>
|
||
Like the blending modes, <code class="constant">B_OP_MIN</code> and <code class="constant">B_OP_MAX</code> work only for color images.
|
||
</p></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Views_Server"></a>Views and the Server</h3></div></div></div><p>
|
||
Windows lead a dual life—as on-screen entities provided by the
|
||
Application Server and as
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> objects in the application.
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>s have
|
||
a similar dual existence—each
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> object has a shadow counterpart
|
||
in the server. The server knows the view's location, its place in the
|
||
window's hierarchy, its visible area, and the current state of its
|
||
graphics parameters. Because it has this information, the server can more
|
||
efficiently associate a user action with a particular view and interpret
|
||
the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s drawing instructions.
|
||
</p><p>
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>s become known to the
|
||
Application Server when they're constructed; creating a
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> object causes the server
|
||
to produce the window that the user will eventually see on-screen. A
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>, on the other hand, has
|
||
no effect on the server when it's constructed. It becomes known to the
|
||
server only when it's attached to a
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>. The server must look through
|
||
the application's windows to see what views it has.
|
||
</p><p>
|
||
A <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> that's not attached to
|
||
a window therefore lacks a counterpart in
|
||
the server. This restricts what some functions can do. Three groups of
|
||
functions are affected:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
Drawing functions—<a class="link" href="BView.html#BView_DrawBitmap" title="DrawBitmap(), DrawBitmapAsync()"><code class="methodname">DrawBitmap()</code></a>,
|
||
<a class="link" href="BView.html#BView_FillRect"><code class="methodname">FillRect()</code></a>,
|
||
<a class="link" href="BView.html#BView_StrokeLine" title="StrokeLine()"><code class="methodname">StrokeLine()</code></a>, and
|
||
so on—don't work for unattached views. A <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> can't draw unless
|
||
it's in a window.
|
||
</p></li><li><p>
|
||
The scrolling functions—<a class="link" href="BView.html#BView_ScrollTo"><code class="methodname">ScrollTo()</code></a>
|
||
and <a class="link" href="BView.html#BView_ScrollBy" title="ScrollBy(), ScrollTo()"><code class="methodname">ScrollBy()</code></a>—require
|
||
the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> to be in a window. Manipulations of a view's coordinate
|
||
system are carried out in its server counterpart.
|
||
</p></li><li><p>
|
||
Functions that indirectly depend on a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s graphics
|
||
parameters—such as
|
||
<a class="link" href="BView.html#BView_GetMouse" title="GetMouse()"><code class="methodname">GetMouse()</code></a>, which reports the cursor location
|
||
in the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s coordinates—also require the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> to belong to a
|
||
window. These functions need information that an unattached <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> can't
|
||
provide.
|
||
</p></li></ul><p>
|
||
However, the functions that set and return graphics parameters—such as
|
||
<a class="link" href="BView.html#BView_SetFont" title="SetFont(), GetFont()"><code class="methodname">SetFont()</code></a>,
|
||
<a class="link" href="BView.html#BView_SetDrawingMode" title="SetDrawingMode(), DrawingMode()"><code class="methodname">SetDrawingMode()</code></a>,
|
||
<a class="link" href="BView.html#BView_PenLocation"><code class="methodname">PenLocation()</code></a>, and
|
||
<a class="link" href="BView.html#BView_SetHighColor" title="SetHighColor(), HighColor() , SetLowColor() , LowColor()"><code class="methodname">SetHighColor()</code></a>—are
|
||
not restricted. A view's graphic state is kept
|
||
within the server (where it's needed to carry out drawing instructions),
|
||
but also cached by the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>. Therefore, it's possible to assign a value
|
||
to a graphics parameter before the server knows about the view. The value
|
||
is simply cached until the view becomes part of a window's view
|
||
hierarchy; the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> then hands it to the server. The server and the
|
||
client-side cache are always kept in synch.
|
||
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Attaching_Window"></a>Attaching to a Window</h4></div></div></div><p>
|
||
Although you can set a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
graphics parameters before it belongs to a
|
||
window and has a counterpart in the Application Server, some of its
|
||
initialization may need to wait until the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> receives an
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>
|
||
notification informing it that it has been added to a
|
||
window's view hierarchy. For example, if a view adopts the background
|
||
color of its parent, it can only set the view color in
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>:
|
||
</p><pre class="programlisting example cpp"><span class="type">void</span> <code class="classname">MyView</code>::<code class="methodname">AttachedToWindow</code>(<span class="type">void</span>)
|
||
{
|
||
if ( <code class="methodname">Parent</code>() )
|
||
<code class="methodname">SetViewColor</code>(<code class="methodname">Parent</code>()-><code class="methodname">ViewColor</code>());
|
||
. . .
|
||
}</pre><p>
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>
|
||
is called for each view that's added to a window,
|
||
beginning with the root view being attached, followed by each of its
|
||
children, and so on down the hierarchy. After all views have been
|
||
notified with an
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>
|
||
function call, they each get an
|
||
<a class="link" href="BView.html#BView_AllAttached"><code class="methodname">AllAttached()</code></a>
|
||
notification, but in the reverse order. A parent view that
|
||
must adjust itself to calculations made by a child view when it's
|
||
attached to a window can wait until
|
||
<a class="link" href="BView.html#BView_AllAttached"><code class="methodname">AllAttached()</code></a> to do the work.
|
||
</p><p>
|
||
These two function calls are matched by another
|
||
pair—<a class="link" href="BView.html#BView_DetachedFromWindow" title="DetachedFromWindow(), AllDetached()"><code class="methodname">DetachedFromWindow()</code></a> and
|
||
<a class="link" href="BView.html#BView_AllDetached"><code class="methodname">AllDetached()</code></a>—which notify
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>s that they're about to be removed from the window.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Preparing_To_Draw"></a>Preparing to Draw</h4></div></div></div><p>
|
||
A <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
doesn't have to draw anything within its frame rectangle—it
|
||
can just be a container for other
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>s that do draw there. However,
|
||
most views that you implement will draw. And most views draw by
|
||
implementing the
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
function. This function is called upon to present
|
||
the view on-screen (or, when printing, on a page). It's implemented using
|
||
the primitive drawing functions listed above. If your
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> includes a
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
implementation, you must include <code class="constant">B_WILL_DRAW</code> in the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s flags
|
||
upon construction.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_The_Update_Mechanism"></a>The Update Mechanism</h4></div></div></div><p>
|
||
The Application Server sends a message to a
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> whenever any of the
|
||
views within the window need to be updated. The
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> then calls the
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
function of each out-of-date
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
so that it can redraw the contents of its on-screen display.
|
||
</p><p>
|
||
Update messages can arrive at any time. A
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> receives one when the
|
||
window is first placed on screen, or is shown after being hidden
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The window is first placed on-screen, or is shown again after having
|
||
been hidden.
|
||
</p></li><li><p>
|
||
Any part of the window becomes visible after being obscured.
|
||
</p></li><li><p>
|
||
The views in the window are rearranged—for example, if a view
|
||
is resized or a child is removed from the hierarchy.
|
||
</p></li><li><p>
|
||
Something happens to alter what a particular view displays. For
|
||
example, if the contents of a view are scrolled, the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> must draw
|
||
any new images that scrolling makes visible. If one of its children
|
||
moves, it must fill in the area the child view vacated.
|
||
</p></li><li><p>
|
||
The application forces an update by "invalidating" a view, or a
|
||
portion of a view.
|
||
</p></li></ul><p>
|
||
As update messages arrive, they jump to the head of the
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>'s message
|
||
queue.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Forcing_An_Update"></a>Forcing an Update</h4></div></div></div><p>
|
||
When a user action or a
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
function alters a view—if the view is scrolled, for example—an update
|
||
message is sent and the <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
function is automatically called. But if the
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> function
|
||
depends on some other state that's defined by your application, you need
|
||
to tell the Application Server that your
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
needs an update message. You do this by invoking
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
|
||
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">Invalidate()</code></a> function.
|
||
</p><p>
|
||
For example, let's say your <code class="classname">D2DView</code> subclass connects some dots by
|
||
reading points out of a
|
||
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a> and drawing lines between them:
|
||
</p><pre class="programlisting example cpp"><span class="type">void</span> <code class="classname">D2DView</code>::<code class="methodname">Draw</code>(<code class="classname">BRect</code> <code class="parameter">update</code>)
|
||
{
|
||
<span class="type">int32</span> <code class="varname">i</code> = 1;
|
||
if (<code class="varname">dotList</code>-><code class="methodname">CountItems</code>() > 1) {
|
||
<code class="methodname">MovePenTo</code>(*(<span class="type">BPoint *</span>)<code class="varname">dotList</code>-><code class="methodname">ItemAt</code>(0);
|
||
while (<code class="varname">i</code> < <code class="varname">dotList</code>-><code class="methodname">CountItems</code>())
|
||
<code class="methodname">StrokeLine</code>(*(<span class="type">BPoint *</span>)<code class="varname">dotList</code>-><code class="methodname">ItemAt</code>(<code class="varname">i</code>++));
|
||
}
|
||
}</pre><p>
|
||
Each "dot specification" is added through <code class="classname">DotView</code>'s
|
||
<code class="methodname">AddDot()</code> function.
|
||
<code class="methodname">AddDot()</code> includes a call to
|
||
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">Invalidate()</code></a>
|
||
in order to force the view to be redrawn:
|
||
</p><pre class="programlisting example cpp"><span class="type">void</span> <code class="classname">D2DView</code>::<code class="methodname">AddDot</code>(<code class="classname">BPoint</code> <code class="parameter">p</code>)
|
||
{
|
||
<code class="varname">dotList</code>-><code class="methodname">AddItem</code>(new <code class="classname">BPoint</code>(<code class="parameter">p</code>));
|
||
<code class="methodname">Invalidate</code>();
|
||
}</pre><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Forcing_An_Update_Whilst_Responding"></a>Forcing an Update while Responding to an Event</h5></div></div></div><p>
|
||
The hook functions that respond to user
|
||
events—<a class="link" href="BView.html#BView_KeyDown" title="KeyDown()"><code class="methodname">KeyDown()</code></a>,
|
||
<a class="link" href="BView.html#BView_MouseDown" title="MouseDown()"><code class="methodname">MouseDown()</code></a>,
|
||
and so on—are executed in the same thread that
|
||
receives window update messages. If you do something in your
|
||
implementation of one of these hook functions that causes an update, the
|
||
update message won't be processed until your hook function exits. If your
|
||
hook function does a lot of processing, your interface can become
|
||
unresponsive.
|
||
</p><p>
|
||
To get around this problem, call
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>'s
|
||
<a class="link" href="BWindow.html#BWindow_UpdateIfNeeded" title="UpdateIfNeeded()"><code class="methodname">UpdateIfNeeded()</code></a>
|
||
function from within your hook functions' implementations.
|
||
<a class="link" href="BWindow.html#BWindow_UpdateIfNeeded" title="UpdateIfNeeded()"><code class="methodname">UpdateIfNeeded()</code></a>
|
||
forces any pending update messages to be processed immediately. The function doesn't
|
||
return until the "dirty" views are all done re-drawing. (Note that
|
||
<a class="link" href="BWindow.html#BWindow_UpdateIfNeeded" title="UpdateIfNeeded()"><code class="methodname">UpdateIfNeeded()</code></a>
|
||
only works from within the
|
||
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>'s
|
||
message loop thread.)
|
||
</p><p>
|
||
For example, let's say you want to add a random dot (within a 100x100
|
||
square) everytime the user hits a key:
|
||
</p><pre class="programlisting example cpp"><span class="type">void</span> <code class="classname">D2DView</code>::<code class="methodname">KeyDown</code>(<span class="type">const char *</span><code class="parameter">bytes</code>, <span class="type">int32</span> <code class="parameter">numBytes</code>)
|
||
{
|
||
<code class="methodname">AddDot</code>(<code class="classname">BPoint</code>(<code class="function">rand</code>()%100, <code class="function">rand</code>()%100);
|
||
<code class="methodname">Window</code>()-><code class="methodname">UpdateIfNeeded</code>();
|
||
...
|
||
}</pre><p>
|
||
Since <code class="methodname">AddDot()</code> calls
|
||
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">Invalidate()</code></a>,
|
||
we know that there's an update message
|
||
pending. However, the update won't normally be processed until
|
||
<a class="link" href="BView.html#BView_KeyDown" title="KeyDown()"><code class="methodname">KeyDown()</code></a>
|
||
exits, so we call
|
||
<a class="link" href="BWindow.html#BWindow_UpdateIfNeeded" title="UpdateIfNeeded()"><code class="methodname">UpdateIfNeeded()</code></a>,
|
||
which sees the update and calls <code class="classname">D2DView</code>'s
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> function. When
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> is finished,
|
||
<a class="link" href="BWindow.html#BWindow_UpdateIfNeeded" title="UpdateIfNeeded()"><code class="methodname">UpdateIfNeeded()</code></a>
|
||
returns and
|
||
<a class="link" href="BView.html#BView_KeyDown" title="KeyDown()"><code class="methodname">KeyDown()</code></a> continues.
|
||
</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Erasing_The_Clipping_Region"></a>Erasing the Clipping Region</h4></div></div></div><p>
|
||
Just before sending an update message, the Application Server prepares
|
||
the clipping region of each
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
that is about to draw by erasing it to
|
||
the view background color. Note that only the clipping region is erased,
|
||
not the entire view, and perhaps not the entire area where the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
will, in fact, draw.
|
||
</p><p>
|
||
The server forgoes this step only if the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s background color is set
|
||
to <code class="constant">B_TRANSPARENT_COLOR</code>.
|
||
See "<a class="link" href="TheInterfaceKit_Drawing.html#TheInterfaceKit_Drawing_View_Color" title="The View Color">The View Color</a>"
|
||
above.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Drawing_During_An_Update"></a>Drawing during an Update</h4></div></div></div><p>
|
||
While drawing, a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
may set and reset its graphics parameters any
|
||
number of times—for example, the pen position and high color might
|
||
be repeatedly reset so that whatever is drawn next is in the right place
|
||
and has the right color. These settings are temporary. When the update is
|
||
over, all graphics parameters are reset to their initial values.
|
||
</p><p>
|
||
If, for example, <a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
sets the high color to a shade of light blue, as shown below,
|
||
</p><pre class="programlisting example cpp"><code class="methodname">SetHighColor</code>(152, 203, 255);</pre><p>
|
||
it doesn't mean that the high color will be blue when
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> is called
|
||
next. If this line of code is executed during an update, light blue would
|
||
remain the high color only until the update ends or
|
||
<a class="link" href="BView.html#BView_SetHighColor" title="SetHighColor(), HighColor() , SetLowColor() , LowColor()"><code class="methodname">SetHighColor()</code></a> is
|
||
called again, whichever comes first. When the update ends, the previous
|
||
graphics state, including the previous high color, is restored.
|
||
</p><p>
|
||
Although you can change most graphics parameters during an
|
||
update—move the pen around, reset the font, change the high color,
|
||
and so on—the coordinate system can't be touched; a view can't be
|
||
scrolled while it's being updated. If the view's coordinate system were
|
||
to change, it would alter the current clipping region and confuse the
|
||
update mechanism.
|
||
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheInterfaceKit_Drawing_Drawing_Outside_Of_An_Update"></a>Drawing outside of an Update</h4></div></div></div><p>
|
||
Graphics parameters that are set outside the context of an update are not
|
||
limited; they remain in effect until they're explicitly changed. For
|
||
example, if application code calls
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>, perhaps in response to an
|
||
interface message, the parameter values that
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> last sets would
|
||
persist even after the function returns. They would become the default
|
||
values for the view and would be assumed the next time
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a> is called.
|
||
</p><p>
|
||
Default graphics parameters are typically set as part of initializing the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> once it's attached to a window—in an
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>
|
||
function. If you want a
|
||
<a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
function to assume the values set by
|
||
<a class="link" href="BView.html#BView_AttachedToWindow" title="AttachedToWindow(), AllAttached()"><code class="methodname">AttachedToWindow()</code></a>,
|
||
it's important to restore those values after any drawing the
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
|
||
does that's not the result of an update. For example, if a
|
||
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> invokes
|
||
<a class="link" href="BView.html#BView_SetHighColor" title="SetHighColor(), HighColor() , SetLowColor() , LowColor()"><code class="methodname">SetHighColor</code></a>
|
||
while drawing in response to an
|
||
interface message, it will need to restore the default high color when
|
||
done.
|
||
</p><p>
|
||
If <a class="link" href="BView.html#BView_Draw" title="Draw()"><code class="methodname">Draw()</code></a>
|
||
is called outside of an update, it can't assume that the
|
||
clipping region will have been erased to the view color, nor can it
|
||
assume that default graphics parameters will be restored when it's
|
||
finished.
|
||
</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheInterfaceKit_Overview_Introduction.html">Introduction</a> Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a> Next: <a href="TheInterfaceKit_Responding.html">Responding to the User</a> </div><div id="footerB"><div id="footerBL"><a href="TheInterfaceKit_Overview_Introduction.html" title="Introduction"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheInterfaceKit_Overview.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheInterfaceKit_Responding.html" title="Responding to the User"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
|
||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
|
||
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
|