TweetFollow Us on Twitter

Regions with CLR
Volume Number:2
Issue Number:2
Column Tag:Basic School

Basic Does Regions (with CLR!)

By Dave Kelly, General Dynamics Corp., MacTutor Editorial Board

Hello! This month we will explore the Macintosh Quickdraw routines with a trip into the world of regions. This may be a review for some of you that program in other languages such as Pascal or C as this subject has been covered quite well in past issues of MacTutor (See Vol. 1 No. 3 "Quickdraw does Regions" or Vol 1 No. 4 "Ports O' Call in Quickdraw"). Until recently it has been impossible to meaningfully talk about regions from MSBASIC. Wth the Clear Lake Research (CLR) Libraries available it is now possible to give BASIC equal time with the other languages when referring to Quickdraw. Quickdraw routines are called from BASIC in much the same method used in Pascal or other languages. In fact, we recommend that you review the Pascal columns referred to above as they have information which may pertain to any language, not just Pascal. The same is true for this column when discussing calls to Quickdraw or other routines used by all languages.

Fig. 1 Screen dump of our regions program

First a bit of a review for those that are not familiar with Quickdraw regions and associated calls. We have available to us via the CLR Libraries [Note: These libraries are available from the MacTutor mail order store for $50 for both the libraries and the speech routines. -Ed.], over 20 statements involving regions. These are found listed with their functions on page 14 of the CLR manual or you may refer to Chapter 4 of Macintosh™ Revealed, Volume One by Chernicoff and published by Hayden Press. Instead of going into a detailed study of Quickdraw I refer you to the previous issues of MacTutor mentioned above. (Back issues are available through the MacTutor Store).

A few things to remember when working with Quickdraw: The horizontal coordinates increase from left to right and the vertical coordinates increase from top to bottom. You may want to think of a region as an area on the screen with a set of points inside the region and a set of points outside. A point in the region cannot be both inside and outside the region. It should also be noted that a graphic point is located to the 'right' and 'below' its corresponding mathematical coordinate.

The Region/Clip Demo program (note: requires CLR Libraries) will set up a region and by using the GetClip and SetClip statements (CLR) we can specify the region which we want the text (or graphics) to be drawn to. In this way, only drawing that occurs within the region will show up on the screen. Any drawing outside the region will not show up. This could be useful when you want to draw in a particular part of the screen without disturbing the contents of another part of the screen. The demo program first opens up the appropriate library:

LIBRARY"ToolLib"

Remember to include the disk volume name if necessary. I would advise you to use the Statement Mover program to move the libraries that you use over to the BASIC program file so they will always follow the program no matter what disk you put it on.

Next we set up some of the array variables used by the program and associated library routines. If the variable is undeclared the libraries cannot work. Also be sure to dimension the arrays properly. For example, if the pattern%() array below were dimensioned to 0 instead of three, the routine SetRect would go ahead and try to store 4 variables, but would only be able to find one. The results could be unpredictable. Save your work before running your program in case there might be any misteaks (ha, ha). The SetRect command sets the left, top, right, and bottom coordinates of the array equal to the indicated values respectively.

DIM R%(3),OvalR%(3),fontinfo%(3),pattern%(3)
x1%=50:y1%=20:x2%=450:y2%=200
SetRect R%(0),x1%,y1%,x2%,y2%
SetRect pattern%(0),&HAA,&HAA,&HAA,&HAA
SetRect pattern%(0),&HAA,&HAA,&HAA,&HAA

The window is opened and the background is set to the background pattern defined in the pattern%() array. The screen is cleared so that the background pattern will be redrawn. The pattern%() array is cleared with SetRect and the background pattern cleared so that subsequent CLS statements will clear the screen to white. Note that the CLS command only clears within the clipping region. When a BASIC window is opened up the clipping region defaults to the window size.

WINDOW 1,"",(2,30)-(508,275),4
CALL BACKPAT (VARPTR(pattern%(0)))
CLS
SetRect pattern%(0),0,0,0,0
CALL BACKPAT(VARPTR(pattern%(0)))

Another CLR Library statement allows us to determine the size of the currently selected font. The program sets the TEXTSIZE to 9 and then calls the getfontinfo routine. The font info is returned in the array fontinfo%(). The variable fontinfo%(0) returns the ascent, fontinfo%(1) returns the descent, fontinfo%(2) returns the maximum character width, and fontinfo%(3) returns the vertical distance between the descent line and the ascent line below it. The program needed to know the total spacing for each line of text which is given by the sum of the ascent, descent, and the vertical distance between the descent line and the ascent line below it. Note that a call to getfontinfo would be useful for programs trying to determine the number of lines of text to print per page (or screen) when using various sizes and styles of fonts.

CALL TEXTSIZE(9)
getfontinfo fontinfo%(0)
fh%=fontinfo%(0)+fontinfo%(1)

Next the region handle variables are defined and the clipping region represented by the screen is stored away so it may be restored again later. If the OldReg! handle were not saved in this way, the last clipping region would be used the next time printing to the window. To define a new region, execute a NewRgn command. This allocates space for the new region and the region is initialized to the empty region. GetClip sets the region with the handle indicated (in this case OldReg! is the handle) to the current clip region.

handle!=0
OldReg!=0
NewRgn OldReg!
getclip OldReg!

We now define the region which we want to use as our clipping region. First we initialize the region with NewRgn with handle! . Next we may define the contents of the region. A series of graphics statements will make up the region we wish to create. We open the region with OpenRgn and follow it with whatever graphics commands we desire such as FRAMEOVAL, FRAMERECT, LINE, and others. Note that arcs cannot form part of the region definition. The end of the definition is indicated with the CloseRgn handle! statement where handle! is the handle! of the region being defined. Next the clipping region is set to the region with handle! with the statement Setclip handle! . All points either printed or drawn outside the region will not be shown. Only those points inside the region may be seen when printing is done inside the region.

NewRgn handle!
OpenRgn
    FRAMEOVAL VARPTR(R%(0))
CloseRgn handle!
Setclip handle!

The next several statements of the program print text in the region which has been set as the clipping region. Note that CLR has provided us with the Drawtext text$ statement to drawtext much faster than with the BASIC PRINT statement. To use drawtext you must move the quickdraw pen to the desired pixel position and issue the drawtext statement. It is harder to use that the BASIC printing statements but the speed difference makes it worth using when speed counts.

There are other statements which may be used with regions. One region may be subtracted from another with DiffRgn or use XorRgn or UnionRgn to combine regions. These and other commands will be left for future MacTutor columns. The program uses the framergn command to draw a border around the edge of the region. The current pensize is used for the border line.

CALL PENSIZE (2,2)
framergn handle!

Now for a word of caution: If your program should crash for some reason before your region is disposed of, you should be prepared to manually type in the disposeRgn statement and appropriate handle or handles for the regions used. Remember to dispose of all regions before quiting your program as the space for the regions has been allocated and will not be returned unless the regions have been disposed of. Otherwise, you may find yourself wondering why you are running out of room on the heap. The statement is:

disposergn handle!

A few words on the CLR Libraries clipping statements: The CLR Libraries manual mentions a statement named ClipRect which is supposed to set the clipping region to a rectangle. The ClipRect routine is not included on my ToolLib file. No need to panic yet, however, because the same command can be reconstructed with a combination of region calls and clipping calls. One solution is to use the following sequence to do a ClipRect (set the clipping region to a rectangle):

DIM rect%(3)
handle!=0
SetRect rect%(0),x1%,y1%,x2%,y2%
NewRgn handle!
OpenRgn
    FRAMERECT ( VARPTR(Rect%(0))
CloseRgn handle!
Setclip handle!

You may also use SetRectRgn or RectRgn to set a region equal to a rectangle. The statement syntax is:

SetRectRgn hand!,left%,top%,right%,bottom%

The region with handle hand! is set equal to the rectangle with coordinates left%,top%,right%, and bottom%.

RectRgn hand!, rect%(0)

The region specified by the handle hand! is set equal to the rectangle rect%. A region is not created by this, but must have been previously defined with NewRgn.

You may use either of these two statements in place of the OpenRgn and CloseRgn sequence above as desired.

Use GetClip to set a region to the current clipping region and SetClip to set the clipping region to a different region. You may want to use SetClip to switch back and forth between different clipping regions.

Have any interesting programs you have created after experimenting with clipping regions? Feel free to share them with others by sending them in to MacTutor.

'Region/Clip Demo
'by Dave Kelly
'MacTutor ©1986

LIBRARY"ToolLib"
DIM R%(3),OvalR%(3),fontinfo%(3),pattern%(3)
x1%=50:y1%=20:x2%=450:y2%=200
SetRect R%(0),x1%,y1%,x2%,y2%
SetRect pattern%(0),&HAA,&HAA,&HAA,&HAA
WINDOW 1,"",(2,30)-(508,275),4
CALL BACKPAT (VARPTR(pattern%(0)))
CLS
SetRect pattern%(0),0,0,0,0
CALL BACKPAT(VARPTR(pattern%(0)))
CALL TEXTSIZE(9)
getfontinfo fontinfo%(0)
fh%=fontinfo%(0)+fontinfo%(1)
handle!=0
OldReg!=0
NewRgn OldReg!
getclip OldReg!
NewRgn handle!
OpenRgn
    FRAMEOVAL VARPTR(R%(0))
CloseRgn handle!
Setclip handle!
CALL MOVETO(x1%,y1%)
FOR i=1 TO 18
    CALL MOVETO (x1%,y1%+i*fh%)
    FOR j=1 TO 6
        drawtext "Read Mac Tutor!  "
    NEXT j
NEXT i
CALL PENSIZE (2,2)
framergn handle!
disposergn handle!
dh%=50:dy%=25
x1%=x1%+dh%:y1%=y1%+dy%
x2%=x2%-dh%:y2%=y2%-dy%
SetRect R%(0),x1%,y1%,x2%,y2%

NewRgn handle!
OpenRgn
    FRAMEOVAL VARPTR(R%(0))
CloseRgn handle!

Setclip handle!
CLS
CALL MOVETO(x1%,y1%)
FOR i=1 TO 18
    CALL MOVETO (x1%,y1%+i*fh%)
    FOR j= 1 TO 6
        drawtext "It's Grrrreat!  "
    NEXT j
NEXT i
framergn handle!
disposergn handle!
Setclip OldReg!
disposergn OldReg!
LIBRARY CLOSE
END
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adium 1.5.10.3 - Popular instant messagi...
Adium is a fast and free instant messaging client which supports AIM, ICQ, Jabber, MSN, Yahoo!, Google Talk, Yahoo! Japan, Bonjour, Gadu-Gadu, Novell Groupwise, SIP/SIMPLE (Text), and Lotus Sametime... Read more
CleanMyMac 3.8.1 - $39.95
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
BusyCal 3.1.7 - Powerful calendar app wi...
BusyCal is an award-winning desktop calendar that combines personal productivity features for individuals with powerful calendar sharing capabilities for families and workgroups. Its unique features... Read more
Lyn 1.8.9 - Lightweight image browser an...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more
Tweetbot 2.5 - Popular Twitter client.
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Monolingual 1.7.8 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. If you use your computer in only one (human) language, you... Read more
Dash 4.0.3 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Posterino 3.3.6 - Create posters, collag...
Posterino offers enhanced customization and flexibility including a variety of new, stylish templates featuring grids of identical or odd-sized image boxes. You can customize the size and shape of... Read more
Apple Numbers 4.1.1 - Apple's sprea...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Apple Pages 6.1.1 - Apple's word pr...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more

Latest Forum Discussions

See All

Die With Glory (Games)
Die With Glory 1.2.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.2.0 (iTunes) Description: Die with Glory is an epic adventure game where your goal is to die in glorious fashion. You must help Sigurd, a brave old... | Read more »
Get Ike in the new Fire Emblem: Heroes u...
One of the most popular Fire Emblem characters is finally available in a new update to Nintendo'sFire Emblem: Heroes. [Read more] | Read more »
Die With Glory in a new viking adventure...
If you're a fan of classic adventure games you'll do well to pick upDie With Glory, the gorgeous new title from Cloud Castle inc. Die With Glory updatesthe gameplay of the same kind of adventure classics such asMonkey Island for modern, mobile... | Read more »
Get up to speed with everything you need...
In case you haven’t heard, MU Origin just got a colossal new update with new all-server events, battle modes, and systems making their way to the land of MU. Here’s a handy guide to everything you need to know about the latest content. [Read... | Read more »
Minimalist puzzle game, Cuts, free on iO...
If you're looking for a gorgeous puzzle experience on iOS devices, developer Gamebra.in's aesthetically interesting puzzler, Cuts, is discounted to free on the iOS App Store right now. [Read more] | Read more »
Anime tactical RPG, War of Crown, comes...
If you're looking for another tactical RPG fix to go alongside your Fire Emblem Heroes campaigns check out Gamevil's newest, anime-inspired tactics RPG, War of Crown, which comes out tomorrow. [Read more] | Read more »
Fantasy MMORPG MU Origin adds new modes,...
MU Origin, Webzen’s highly popular fantasy MMORPG is getting ready to shake things up for the second time this year, as a new update makes its way to the Google Play and App Store from today. Introducing new systems, modes, and events, the land of... | Read more »
Blizzard is looking to hire a mobile dev...
A new thread on the popular video game rumor forum, NeoGAF, uncovered an interesting job listing over at Blizzard Entertainment. It appears the studio behindStarCraft, World of WarCraft, Hearthstone,andOverwatch is looking to bring on a new hire... | Read more »
Legend of Zelda meets Cooking Mama in ne...
Dungeon Chef is what happens when you mix the RPG elements (and style) of a Legend of Zelda game, with cooking elements. Although, now that The Legend of Zelda: Breath of the Wild also has cookingelements, so maybe the gameplay is not so novel.... | Read more »
ChordFlow (Music)
ChordFlow 1.0.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0.0 (iTunes) Description: ChordFlow is a chord sequencer with a unique 4-track polyphonic arpeggiator, extensive chord library, MIDI out and Ableton Link... | Read more »

Price Scanner via MacPrices.net

Digital Paper Tablet Offers Distraction Free...
I typically spend 8-10 hours a day gazing at the screens in my laptops and iPad, as tools of my livelihood, I don’t as a rule use electronic devices for pleasure reading. I subscribe to a daily... Read more
“Today at Apple” Bringing New Educational Ses...
Apple has announced plans to launch dozens of new educational sessions next month in all 495 Apple Stores ranging in topics from photo and video to music, coding, art and design, and more. The hands-... Read more
Smart Finance Free Comprehensive Personal Fin...
Moscow-based indie developer, Alexander Survillo has announced the release and immediate availability of Smart Finance: Personal Finance, Budget & Money 1.1.4, an update to his comprehensive... Read more
12-inch 1.1GHz Retina MacBooks on sale for $1...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199.99 $100 off MSRP - 12... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 13″ 2.7GHz Retina MacBook Pro on sale for $130 off MSRP. Shipping is free, and B&H charges NY & NJ tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $1169 $... Read more
15-inch 2.2GHz Retina MacBook Pros available...
B&H Photo has the 15″ 2.2GHz Retina MacBook Pro available for $200 off MSRP including free shipping plus NY & NJ sales tax only: - 15″ 2.2GHz Retina MacBook Pro (MJLQ2LL/A): $1799.99 $200 off... Read more
13-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the 2016 Apple 13″ Touch Bar MacBook Pros in stock today for up to $150 off MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 13″ 2.9GHz/512GB Touch Bar... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H has 12″ 1.2GHz Retina MacBooks on sale for up to $160 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.2GHz Space Gray Retina MacBook: $1439.99 $160 off MSRP - 12″ 1... Read more
HyperX Ships Pulsefire FPS Gaming Mouse, Winn...
Your reporter is a longtime fan of gaming mice for general purpose coomnputing use, finding them typically superior in comfort and performance. HyperX, a division of Kingston Technology Company, Inc... Read more

Jobs Board

*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
Product Manager, *Apple* Platforms - Viacom...
…Product Manager to drive the execution of its iOS and AppleTV experiences. The Apple Platform Product Manager will be a leader in our Agile/Scrum environment and Read more
Geek Squad *Apple* Master Consultation Agen...
**500662BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Location Number:** 000286-Canton-Store **Job Description:** **What does a Geek Squad Read more
*Apple* Mobile Master - Best Buy (United Sta...
**500710BR** **Job Title:** Apple Mobile Master **Location Number:** 000279-North Olmsted-Store **Job Description:** **What does a Best Buy Apple Mobile Master Read more
*Apple* Engineering Specialist - CSRA (Unite...
Apple Engineering Specialist All times are in Eastern Daylight Time Requisition ID Job Locations US DC Washington DC Posted Date Category Engineering Sciences Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.