TweetFollow Us on Twitter

Window Structures
Volume Number:5
Issue Number:6
Column Tag:abC

Related Info: Window Manager

Window Structures

By Bob Gordon, Minneapolis, MN

Welcome to the second incarnation of the MacTutor intro column. The column is called abC because of its introductory nature (the “abc’s”), and it uses the C language (the “C”). What I propose to do is to continue in the spirit of the previous set of articles, but focus less on C and more on the Mac.

I also will not attempt to present a complete program each time. Since an introduction by its very nature tends to be a bit repetitive, I found the last time that the same code would appear for months at a time. This took up a lot of space in the magazine, and made it difficult to focus on one issue as we were always carrying around a large amount of other code just to make an application work. This means that the articles will tend to be shorter, which will likely make it more possible for me to get them done.

One other point before we start. I found that one of the most useful things in writing for MacTutor is getting mail. Feel free to write; comments are much appreciated; and include your phone number.

Making a Window

One of the first steps in a Mac application is putting a window on the screen, typically in response to a request from the user. This method developed here is done entirely in code (as opposed to using resources). This has some limits, but offers the ability to easily add some features to ease the maintenance of windows.

There are two points: First a window consists of the window stuff and the application specific stuff. From the Mac’s point of view, the window stuff consists of only the frame and does not even include the scroll bars (if any). On the other hand the application probably does not want to be concerned with such things as the scroll bars, zoom boxes, sizing, et cetera.

Second, it is good programming practice to separate the application specific code from the more generic user-interface code. This eases maintenance and debugging and modification. To this end I created a file, shell.c which handles many of the generic properties, helper files (e.g. windowhelp.c) to add the capabilities I wanted, and the file app.c, which actually contains the parts of the application. In the snippets of code that follow, you will notice an occasional call to a function like appxxx(). This is a call in the shell part of the program to the app.c file. It is here, after, for example, preparation has been made for updating a window (appupdate() ), that the application must update the application portion.

windowhelp.h

The windowhelp functions work because the WindowRecord defined in the ToolBox is a fixed length object. What I did is add some additional data structures on the end. This simply makes the object a little longer, but all the toolbox window and QuickDraw functions will work correctly. The advantage of doing this is that I can now keep additional information, which I think should be attached to a window in a safe place where I can always find it, and the application parts of the code need to concern themselves with it.

One might suggest that the WRefCon (a field in the WindowRecord specifically for the application’s own use) field is the proper place for this. This is probably true, but so much of this stuff seemed to either be more part of the window than the application (scroll bars) or likely to be part of any application (knowing whether the contents had changed or not), that it seemed a Good Idea to put it all together in one place. In this way much of the Mac user interface is handled for us each time we start a project. I use the WRefCon field to store the reference to the applications information proper.

Now, I make have no pretenses that this is the optimal way of doing things. In fact, I know there are additions and changes I am going to make, but if we wait to get all that worked out, we’ll never get this written.

A few comments about the fields:

The first four are what I call window margins. I noticed that many applications place various graphic objects around the edges of the window. There are scroll bars to the bottom and right, rulers on the top and tools on the left. Whatever it is, it brings in the edge of the window as far where the application can write. The window margins are sizes, in pixels of the areas reserved by things around the edges. The application can change them (if the user asks to see the rulers, for example).

The next field, cursrt, is the rectangle defined by the window and the margins. I called it cursrt because outside the rectangle the cursor is typically the 11 o’clock arrow, and inside the cursor is whatever the application would like.

The zoomrt is the rectangle to hold the size to zoom to if the user clicks the zoom box. Frankly, I haven’t implemented zooming yet. It may be that we’ll want two rectangles for zooming: one to hold the maximum size and one to hold the small (user set) size.

mouser is a code for the mouse cursor. I made it a char simply because I couldn’t imagine anyone wanting more than 255 cursors and because the built-in cursors are numbered one through four. If you want to add a cursor resource, simply start the numbers at five and everything will work fine. And if you want more cursors or want to use bigger numbers, make it a short.

The changed field simply states whether or not the window contents have changed.

The next field, ckind (contents kind) I used to indicate the kind of window. Currently this is either text or a object drawing. Whether this will stay this way or not I don’t know. Currently I use this in the functions that handle update and activation events to determine what to do.

The last field is a handle to the current TextEdit record. A window may have more than one. This is needed because when a window is activated, the blinking cursor needs to be placed in whichever edit record the user left it in.

As you can see, much of this information falls somewhere between what is strictly application specific and what is part of the window. Much of it, however, the application either need not be concerned with or is needed for almost all applications.

Following the WindowStruct definition are several groups of #defines. The most interesting of these are the WDOC/WGROW/WZOOM. By using these when you define a window (simply add together the ones you want), you can specify whether you want a simple document window to have a grow box or a zoom box. You can also add in the codes for the vertical or horizontal scroll bars.

/* 1 */

/*windowhelp.h */
#include “TextEdit.h”
 
#ifndef WINDOWHELP_H
#define WINDOWHELP_H

/* window add-on structure */

#define WindowStruct struct w_struct
WindowStruct
 {
 WindowRecord  wr; /* the original window record */
 uchar  mtop;    /* margin indents */
 uchar  mleft;
 uchar  mbottom;
 uchar  mright;
 Rect   cursrt;  /* rectangle used for cursor control */
 Rect   zoomrt;  /* rectangle for zoom operation */
 char   mouser;  /* mouse pointer id (cursor shape) */
 char   changed; /*if window contents havebeen changed */
 short  ckind;   /* kind of contents */
 TEHandle curtext; /* handle current te rec for window */
 };
 

#define Woffset  18
#define SBarWidth15

/* these definitions allow easy generation of the four square
 * cornered titled windows. The basic (simplest) window is the
 * WDOC (NoGrowDocProc). To this optionally add WGROW to add a 
 * grow box and/or WZOOM to add a zoom box.
 */
#define WDOC4
#define WGROW    -4
#define WZOOM    8
#define WVBAR    16
#define WHBAR    32

/* specify the content of the window */
#define CDRAW    1
#define CTEXT    2

/* Value in windowKind field of WindowRecord by WindowNew
 * if the window has a grow box. This is used by routines that
 * redraw the window to decide whether to draw the grow box
 * or not 
 */
#define HASGROW  9

#endif

WindowHelp.c

WindowHelp.c consists mainly of two functions, WindowNew() and WindowClose().

WindowNew() opens a window after creating a WindowStruct as shown above (no check for memory yet). Note that it only gets four arguments. The title (which can be a null string in which case the window is named “Untitled”), a percentage (the window is opened as a certain percentage of the monitor size), the windowkind (WDOC/WGROW/WZOOM), and the content kind.

A few other notes: The call to AppPage() is a kludge. It is supposed to return the page size. Currently some numbers are just hard coded in AppPage(). The page size is needed for scrolling. Just put in sizes for an 8.5 by 11 piece of paper (in pixels) or whatever size page you want. The call to AppNew() is where the application does the initialization of its own data for a new window and places a reference to it (typically a handle) in the WRefCon.

WindowClose() closes a window. After checking to see if the window is a desk accessory (and handling that), it calls AppClose() to allow the application to close its own structures. Then is closes the window and frees the memory. It is in here that we would check to see if the window contents had changed (and had not been saved) and ask the user if we were to save the file.

/*2 */


/* windowhelp.c
 * provides some routines to aid in opening and closing 
 * windows
 */
 
#include“abc.h”
#include“Quickdraw.h”
#include“EventMgr.h”
#include“WindowMgr.h”
#include“MenuMgr.h”
#include“windowhelp.h” 
#include“controlhelp.h”
#include“cursorhelp.h”

short w_total = 0; /* counts total number of windows opened*/
short w_count  = 0;
 /* counts number of windows actually open */

WindowNew(title,percentsz,windkind,contkind)
 char *title;
 short  percentsz;
 short  windkind;
 short  contkind;
{
 char   *thetitle;
 Rect   boundsrt;
 WindowRecord  *w;
 WindowStruct  *ws;
 short  width;
 short  depth;
 short  leftedge;
 short  topedge;
 Rect   pagesz;
 short  hasscroll;
 
 hasscroll = windkind & WVBAR + WHBAR; 
 /* mask out scroll bar options */
 windkind &= 8;
 if (title)
 thetitle = title;
 else
 thetitle = “Untitled”;
 SetRect(&boundsrt,screenBits.bounds.left + 4,
 screenBits.bounds.top + 24,
 screenBits.bounds.right - 4,
 screenBits.bounds.bottom - 4);
 width = boundsrt.right - boundsrt.left;
 depth = boundsrt.bottom - boundsrt.top;
 AdjustRect(&boundsrt,
 topedge = 30 + Woffset * w_total,
 leftedge = 30 + Woffset * w_total,
 ((depth * percentsz) / 100) - topedge,
 ((width * percentsz) / 100) - leftedge);
 ws = (WindowStruct *)NewPtr(sizeof (WindowStruct));
 w = (WindowRecord *)NewWindow(ws,&boundsrt,CtoPstr(thetitle),True,
 windkind,(WindowPtr)-1,True,0);
 ws = (WindowStruct *)w;
 switch (windkind)
 {
 case documentProc : 
 case zoomDocProc :
 w->windowKind = HASGROW;
 break;
 };
 if (w->windowKind == HASGROW)  /* set window margins */
 {
 ws->mright = ws->mbottom = SBarWidth;
 AppPage(&pagesz);
 if (hasscroll == WHBAR)
 ScrollNew(w,0,0,pagesz.right,HORZ);
 if (hasscroll == WVBAR)
 ScrollNew(w,0,0,pagesz.bottom,VERT);
 DrawControls(w);
 DrawGrowIcon(w);
 }
 else
 ws->mright = ws->mbottom = 0;
 ws->mtop = ws->mleft = 0;
 ws->changed = FALSE;
 ws->ckind = contkind;
 ws->curtext = NIL;
 SetCursorRect(w); /* set cursor rect for cursor control */
 AppNew(w); /* function to open application structure */
 w_count++;
 w_total++;
 PtoCstr(thetitle);
}

/* WindowClose()
 * Closes the window passed to it. Assumes window was opened 
 * with WindowNew(). If window is a desk accessory, it will 
 *  be closed correctly. If it is an application window, prior 
 *  to the window close there is a call to AppClose() (which 
 * the application must supply) to allow any application 
 * specific closing.
 */
WindowClose(w)
 WindowRecord  *w;
{
 WindowStruct  *ws;
 short  refnum;
 
 if (ws = (WindowStruct *)w)
 if ((refnum = w->windowKind) < 0)
 CloseDeskAcc(refnum);
 else 
 {
 AppClose(w);    /* close app storage, must do before */
   CloseWindow(w); /*    CloseWindow */
   DisposPtr(w);
   w_count--;    /* decrement the window count */
   if (w_count == 0) 
 /* if the number of windows on screen goes to */
   w_total = 0;  
 /*  zero, set total to zero so next time we */
   }    /* open a window it will start at the original */
}/*   window position */

/* AdjustRect
 * adjusts coordinates of a rectangle by four separate 
 * amounts. adjustment is in (towards center) if amounts are 
 * positive and out if amounts are negative);
 */
AdjustRect(rec,t,l,b,r)
 Rect *rec;
 short  t,l,b,r; /* values to adjust rectangle by */
{
 rec->top +=t;
 rec->left += l;
 rec->bottom -= b;
 rec->right -= r;
}

/* RtGlobalToLocal
 * Adjusts a rectangle to local coordinates
 */
RtGlobalToLocal(rt)
 Rect *rt;
{
 Point  *pt;
 
 pt = (Point *)rt;
 GlobalToLocal(pt);
 pt++;
 GlobalToLocal(pt);
}

The last little piece of code illustrates how these functions are called from the shell program.dofile() is part of the code that responds to menus.

/* 3 */

dofile(item)
 short  item;
{
 WindowRecord  *w;
 
 switch(item)
 {
 case iNew: WindowNew(“”,40,WDOC+WGROW+WVBAR,CTEXT);
   break;
 case iClose: WindowClose(FrontWindow());
   break;
 case iQuit : while (w = (WindowRecord *)FrontWindow() )
 {
 WindowClose(w);
 }
   ExitToShell();
   break;
 }
}

I hope this gives you some ideas on how to handle windows. Since it can open as many windows as you want, there should be some check for memory limits. I also hope this is suitably introductory. Again, if you have any questions or comments, please write.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Duplicate Annihilator 5.7.5 - Find and d...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator... Read more
BusyContacts 1.0.2 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Capture One Pro 8.2.0.82 - RAW workflow...
Capture One Pro 8 is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 300 high-end cameras -- straight out of the box. It... Read more
Backblaze 4.0.0.872 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac.With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Little Snitch 3.5.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Monolingual 1.6.4 - 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
CleanApp 5.0 - Application deinstaller a...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
Fantastical 2.0 - Create calendar events...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event details... Read more
Cocktail 8.2 - General maintenance and o...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Direct Mail 4.0.4 - Create and send grea...
Direct Mail is an easy-to-use, fully-featured email marketing app purpose-built for OS X. It lets you create and send great looking email campaigns. Start your newsletter by selecting from a gallery... Read more

These are All the Apple Watch Apps and G...
The Apple Watch is less than a month from hitting store shelves, and once you get your hands on it you're probably going to want some apps and games to install. Fear not! We've compiled a list of all the Apple Watch apps and games we've been able to... | Read more »
Appy to Have Known You - Lee Hamlet Look...
Being at 148Apps these past 2 years has been an awesome experience that has taught me a great deal, and working with such a great team has been a privilege. Thank you to Rob Rich, and to both Rob LeFebvre and Jeff Scott before him, for helping me... | Read more »
Hands-On With Allstar Heroes - A Promisi...
Let’s get this out of the way quickly. Allstar Heroes looks a lot like a certain other recent action RPG release, but it turns out that while it’s not yet available here, Allstar Heroes has been around for much longer than that other title. Now that... | Read more »
Macho Man and Steve Austin Join the Rank...
WWE Immortals, by Warner Bros. Interactive Entertainment and WWE, has gotten a superstar update. You'll now have access to Macho Man Randy Savage and Steve Austin. Both characters have two different versions: Macho Man Randy Savage Renegade or Macho... | Read more »
Fearless Fantasy is Fantastic for the iF...
I actually had my first look at Fearless Fantasy last year at E3, but it was on a PC so there wasn't much for me to talk about. But now that I've been able to play with a pre-release version of the iOS build, there's quite a bit for me to talk... | Read more »
MLB Manager 2015 (Games)
MLB Manager 2015 5.0.14 Device: iOS Universal Category: Games Price: $4.99, Version: 5.0.14 (iTunes) Description: Guide your favorite MLB franchise to glory! MLB Manager 2015, officially licensed by MLB.com and based on the award-... | Read more »
Breath of Light (Games)
Breath of Light 1.0.1421 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1421 (iTunes) Description: Hold a quiet moment. Breath of Light is a meditative and beautiful puzzle game with a hypnotic soundtrack by... | Read more »
WWE WrestleMania Tags into the App Store
Are You ready to rumble? The official WWE WrestleMania app, by World Wrestling Entertainment, is now available. Now you can get all your WrestleMania info in one place before anyone else. The app offers details on superstar signings, interactive... | Read more »
Bio Inc's New Expansion is Infectin...
Bio Inc., by DryGin Studios, is the real time strategy game where you infect a human body with the worst virus your evil brain can design. Recently, the game was updated to add a whole lot of new features. Now you can play the new “Lethal”... | Read more »
The Monocular Minion is Here! Despicable...
Despicable Me: Minion Rush, by Gameloft, is introducing a new runner to the mix in their latest update. Now you can play as Carl, the prankster minion. Carl has a few new abilities to play with, including running at a higher speed from the start.... | Read more »

Price Scanner via MacPrices.net

13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
Save up to $80 on iPad Air 2s, NY tax only, f...
 B&H Photo has iPad Air 2s on sale for $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469.99 $30 off - 64GB iPad Air 2 WiFi: $549.99 $50 off - 128GB iPad... Read more
iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Färbe Technik Offers iPhone Battery Charge LI...
Färbe Technik, which manufactures and markets of mobile accessories for Apple, Blackberry and Samsung mobile devices, is offering tips on how to keep your iPhone charged while in the field: •... Read more
Electronic Recyclers International CEO Urges...
Citing a recent story on CNBC about concerns some security professionals have about the forthcoming Apple Watch, John Shegerian, Chairman and CEO of Electronic Recyclers International (ERI), the... Read more
Save up to $380 with Apple refurbished iMacs
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
Mac minis on sale for up to $75 off, starting...
MacMall has Mac minis on sale for up to $75 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: - 1.4GHz Mac mini: $459.99 $40 off - 2.6GHz Mac... Read more
College Student Deals: Additional $50 off Mac...
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through April 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more

Jobs Board

DevOps Software Engineer - *Apple* Pay, iOS...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
Lead *Apple* Solutions Consultant - Retail...
**Job Summary** Job Summary The Lead ASC is an Apple employee who serves as the Apple business manager and influencer in a hyper-business critical Reseller's store Read more
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.