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.

 
AAPL
$107.18
Apple Inc.
-0.16
MSFT
$46.18
Microsoft Corpora
-0.44
GOOG
$551.43
Google Inc.
+2.10

MacTech Search:
Community Search:

Software Updates via MacUpdate

LibreOffice 4.3.3.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
VMware Fusion 7.0.1 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
OneNote 15.3.2 - Free digital notebook f...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Audio Hijack Pro 2.11.4 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Iridient Developer 3.0.0 beta 3 - Powerf...
Iridient Developer (was RAW Developer) is a powerful image conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more
TextWrangler 4.5.11 - Free general purpo...
TextWrangler is the powerful general purpose text editor, and Unix and server administrator's tool. Oh, and also, like the best things in life, it's free. TextWrangler is the "little brother" to... Read more
NeoFinder 6.6 - Catalog your external me...
NeoFinder (formerly CDFinder) rapidly organizes your data, either on external or internal disks, or any other volumes. It catalogs all your data, so you stay in control of your data archive or disk... Read more
Chromium 38.0.2125.111 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Default Folder X 4.6.11 - Enhances Open...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more
Mariner Write 3.9.3 - Light-weight and s...
Mariner Write is your Mac OS go-to word processing tool! Professional writer, educator or student, Write has all the functionality you need for that important letter, technical paper or research... Read more

Latest Forum Discussions

See All

Naailde the Witch Review
Naailde the Witch Review By Amy Solomon on October 30th, 2014 Our Rating: :: PITCH-PERFECT STORYTELLINGUniversal App - Designed for iPhone and iPad Marvelous storytelling, narration, and moving illustrations make this storybook... | Read more »
1st & Goal Review
1st & Goal Review By Andrew Fisher on October 30th, 2014 Our Rating: :: FOR THE D&D LOVING QBUniversal App - Designed for iPhone and iPad 1st & Goal is a board gamer’s football game, a football fan’s board game, and... | Read more »
French Developer Pated Unveils Seashine
French Developer Pated Unveils Seashine Posted by Ellis Spice on October 30th, 2014 [ permalink ] French one-man studio Pated has unveiled Seashine, “a poetic journey into the abyss.” Players take on the role of a jellyfish strugglin | Read more »
Agents of Storm: Tips, Tricks, and Strat...
Calling all agents: Would you like to see what we thought of this rather pretty base builder? Check out our Agents of Storm review! Have you downloaded Agents of Storm, been bowled over by the graphics, and aren’t quite sure what to do next? Never... | Read more »
Any.DO 2.0 Hopes to Help Manage Producti...
Any.DO 2.0 Hopes to Help Manage Productivity Posted by Ellis Spice on October 30th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
Base Busters Review
Base Busters Review By Jennifer Allen on October 30th, 2014 Our Rating: :: FUN BUT RESTRICTED MIXUniversal App - Designed for iPhone and iPad Mixing up two forms of tower defense gaming and collectible cards, Base Busters is a fun... | Read more »
Sumptus - Personal Expense Tracker in Yo...
Sumptus - Personal Expense Tracker in Your Pocket 1.0 Device: iOS iPhone Category: Finance Price: $3.99, Version: 1.0 (iTunes) Description: Sumptus - a personal finance assistant in your pocket. It’s an ultimate expense tracker... | Read more »
Meat Factory (Games)
Meat Factory 0.1 Device: iOS Universal Category: Games Price: $.99, Version: 0.1 (iTunes) Description: Meat factory harks back to the old days of the game and watch. Easy to pick up and play, but hard to score big. With cute visuals... | Read more »
Medford Asylum: Paranormal Case - Hidden...
Medford Asylum: Paranormal Case - Hidden Object Adventure (Full) 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Uncover the mystery of Medford City asylum! | Read more »
Secret Files Sam Peters (Games)
Secret Files Sam Peters 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: [ After the successful iOS release of Secret Files Tunguska, the acclaimed point and click adventure Secret Files... | Read more »

Price Scanner via MacPrices.net

Apple now offering refurbished 2014 15-inch M...
The Apple Store is now offering Apple Certified Refurbished 2014 15″ Retina MacBook Pros for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Apple drops prices on refurbished 2013 Retina...
The Apple Store has dropped prices on 2013 Apple Certified Refurbished 13″ and 15″ Retina MacBook Pros, with Retina models now available starting at $999. Apple’s one-year warranty is standard, and... Read more
New 2.8GHz Mac mini on sale for $949, save $5...
Abt Electronics has the new 2.8GHz Mac mini in stock and on sale for $949.05 including free shipping. Their price is $50 off MSRP, and it’s the lowest price available for this model from any reseller... Read more
Sale! 3.7GHz Quad Core Mac Pro available for...
 B&H Photo has the 3.7GHz Quad Core Mac Pro on sale for $2649 including free shipping plus NY sales tax only. Their price is $350 off MSRP, and it’s the lowest price for this model from any... Read more
Mujjo Steps Up The Game With Refined Touchscr...
Netherlands based Mujjo have just launched their Refined Touchscreen Gloves, stepping up their game. The gloves feature a updated elegant design that takes these knitted gloves to the next level. A... Read more
Sale! Preorder the new 27-inch 5K iMac for $2...
 Abt Electronics has the new 27″ 3.5GHz 5K iMac on sale and available for preorder for $2374.05 including free shipping. Their price is $125 off MSRP, and it’s the lowest price available for this... Read more
Simplex Solutions Inc. Brings Secure Web Surf...
New York based Simplex Solutions Inc. has announced the release and immediate availability of Private Browser 1.0, its revolutionary new secure web browser developed for iPhone, iPad and iPod touch... Read more
Save up to $180 off MSRP with an Apple refurb...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Apple refurbished 2013 MacBook Pros available...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more
What Post PC Era? – The Mac Bounces Back, Big...
Apple’s fiscal Q4 2014 was an all-time record quarter for Mac sales, with 5.5 million units shipped, representing nearly one million more sales (+21 percent, + 25 percent sequentially) than Apple... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.