TweetFollow Us on Twitter

Definition Routines
Volume Number:2
Issue Number:7
Column Tag:Pascal Procedures

Introduction to Definition Routines

By Darryl Lovato, Lovato Programming, Salt Lake City, UT

Introduction

This is the first of a series of articles which will cover Macintosh Definition Routines. I will use TML Pascal for all the programming examples because it is rapidly becoming the most popular Development System on the Mac, and because the new TML linker will allow you to create procedure resources (MDEF's PROC's WDEF's FKEY's ect.) quickly and efficiently.

This month I will cover the issues in common to all the different types of definition routines. In the following months I will cover Menu definition routines (MDEF's), Window definition routines (WDEF's), Control definition routines (CDEF's), List definition routines (LDEF's), and function key routines (FKEY's) in depth.

Defintion routines allow you to create a variation of a standard type of "Object" to better fit your needs. That is, they effect the general appearance and behavior of whatever they define. The pattern selection Menu in MacDraw is a good example of this. Definition routines are usually stored as resources but they may also be set up as routines within your program.

The best way to develop a Definition Routine is to make it a routine in your code, and when its finished, to compile it into a resource which can then be used with any application. The Menu, Window, Contol, and List managers all allow you to use definition routines.

Fig. 1 A non-standard Menu Item

Getting a Handle On Things

When you create a new object (menu, window ect.), you can specify a non-standard definition routine (a routine other than the normal Mac ROM way of doing something) for it to use. There are two ways of doing this.

1. By making the procedure a resource in a seperate file.

An example of this process for a non-standard menu follows. Listing #1 is the code that creates the Menu Definition Resource and listing #2 shows how to use it.

{---------listing fragment #1 the resource def program-------}
{must be compiled with the DeskAcc option checked}
program TheMDEFProc;

{pascal directive to create a MDEf resource}
{---> $C type id [attribute] [name] <---}

{$C 'MENU' 256 4 'TheMDEFRes'}

var { no globals allowed }

  procedure theMDEFProcedure(...);

  begin
    { code to impliment the Menu Def }
  end;

begin {no main program allowed}
end.

{------listing fragment #2 the program that uses the res-----}

program UseTheMenu;

{$L TheMDEFProc} {link the file we created above}
          {it includes the menu def we created}

Two methods can be used to put a handle to your MDEF resource in the MenuProc field of the menu.

(1) In the menu resource, change the menuID field to the resource id of your MDEF. Then,when you call the GetMenu function, the Menu Manager will automatically read the MDEF resource from the resource file, and place a handle to it in the MenuProcField of the menu

(2) If you create the menu (or window) by any means other than reading a resource (by calling NewMenu, for instance), you must get a handle to the MDEF by executing the following code:

 MyMenuHand := NewMenu(100,'menuTitle');
 myProcHdl := GetResource('MDEF',256);
 MyMenuHand^^.menuProc := myProcHdl;

2. By putting the proc in your code and creating a handle to it.

First get a handle to your object, by calling NewMenu or GetNewMenu. Then get a handle to the definition routine, which may be part of your code, and shove it into the MenuProc field of your objects record. An Example of this method follows:

var
 myMenuHdl : MenuHandle;

procedure TheMenuProc(...);
begin
.
.
.
end;
.
.
.
myMenuHdl := GetNewMenu(...);
myMenuHdl^^.menuProc := NewHandle(0);
myMenuHdl^^.menuProc^ := Ptr(@TheMenuProc);

Fig. 2 A non-standard window definition

Things to Come

All of the definition routines are passed a message which tell them what kind of action the are to do. Typical actions are Initialize, Draw, Select, Drag, Size, ect. A brief introduction to the individual definition routines we will cover in the in the next couple of months follow:

Menu Defintion Procedure

The menu definition procedure has the following Pascal definition:

procedure MyMenu(message : integer;
 theMenu : MenuHandle;
 var menuRect : Rect;
 hitPt : Point;
 var whichItem : Integer);

The message parameter tells you what kind of action to take, it may be one of the following values:

mDrawMsg

If the menu definition procedure is passed this value it should draw theMenu inside menuRect.

mChooseMsg

If the menu definition procedure is passed this value it should hilite the item which hitPt is in, unhilite the old item, and return the new item in whichItem.

mSizeMsg

If the menu definition procedure is passed this value it should calculate the width and height of the menu and put the results in theMenu^^.width and theMenu^^.height respectively.

Window Defintion function

The window definition function has the following Pascal definition:

function MyWindow(varCode : integer;
 theWindow : WindowPtr;
 message : integer;
 param : LongInt)
 : LongInt;

The message parameter tells you what kind of action to take, it may be one of the following values:

wDraw

If the window definition function is passed this value it should draw the window frame. Before doing this, however, the routine should check to see if the window frame should show hiliting, if the window is visible, if the window has a go-away box, ect.

wHit

If the window definition function is passed this value it should inspect param, which is the point where the mouse was pressed. Then it should check to see if the point is in one of the windows regions, such as the GoAway region, and return the appropriate result.

wCalcRgns

If the window definition function is passed this value it should calculate the windows current structure and content regions and store the results in the window record.

wNew

If the window definition function is passed this value it should perform any extra initialization and allocation it may require.

wDispose

If the window definition function is passed this value it should perform any additional disposal actions which it may require. This message "Undo's" whatever was done in the wNew routine.

wGrow

If the window definition function is passed this value it should draw a grow image of the window to fit the given rectangle. This operation is called repeatedly when the user drags inside the grow region.

wDrawGIcon

If the window definition function is passed this value it should draw the size box icon in the window.

Control Defintion Function

The control definition function has the following Pascal definition:

function MyControl(varCode : integer;
 theControl : ControlHandle;
 message : integer;
 param : LongInt)
 : LongInt;

The message parameter tells you what kind of action to take, it may be one of the following values:

drawCntl

If the control definition function is passed this value it should draw all or part of theControl.

testCntl

If the control definition function is passed this value it should test where the mouse button was pressed.

calcCRgns

If the control definition function is passed this value it should calculate the control or its indicators regions.

initCntl

If the control definition function is passed this value it should do any extra initialization actions it needs to perform.

dispCntl

If the control definition function is passed this value it should take any additional disposal actions.

posCntl

If the control definition function is passed this value it should reposition the controls indicator, and update it.

thumbCntl

If the control definition function is passed this value it should calculate parameters for dragging indicator.

dragCntl

If the control definition function is passed this value it should drag the control or its indicator.

autoTrack

If the control definition function is passed this value it should execute the control's action procedure.

List Defintion Procedure

The list definition procedure has the following Pascal definition:

procedure MyList(lmessage : integer;
 lSelect : Boolean;
 lRect : Rect;
 lCell : Cell;
 lDataOffset : integer;
 lDataLen : integer;
 lHandle : ListHandle);

The message parameter tells you what kind of action to take, it may be one of the following values:

lInitMsg

If the list definition procedure is passed this value it should do any additional list initialization.

lDrawMsg

If the list definition procedure is passed this value it should draw the cell.

lHiliteMsg

If the list definition procedure is passed this value it should invert the cell's highlite state.

lCloseMsg

If the list definition procedure is passed this value it should take any additional disposal actions.

A Warning From Apple

Apple has stated, "For the convienience of the application's user, remember to conform to the Macintosh User Interface Guidlines as much as possable". I agree totally. So don't make a round menu or a window in the shape of a Apple. (I've already done them both anyway!) [Wow! How about publishing the Apple window? -Ed.]

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Gordon Ramsay DASH: Guide to upgrading a...
If we've learned anything about celebrity chef Gordon Ramsay over the years, it's that you don't want him angry and breathing down your neck. He's not above calling you out on TV, making a mockery of your efforts in the kitchen in front of... | Read more »
Galaxy of Trian (Games)
Galaxy of Trian 1.1.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.1.0 (iTunes) Description: Galaxy of Trian is an exciting, fast paced digital board game based on the highly acclaimed tabletop title. | Read more »
Dead In Bermuda (Games)
Dead In Bermuda 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
The Little Fox (Games)
The Little Fox 1.0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1 (iTunes) Description: The Little Fox is an alternative perspective on the world-renowned ‘fairy tale for adults', The Little Prince by Antoine de... | Read more »
5 popular free fertility apps
There was a good article this week in The Independent about how more women are using fertility appsas a de facto form of contraception. It's apparently not working too well, leading to numerous unwanted pregnancies. [Read more] | Read more »
How to get more cars in CSR Racing 2
NaturalMotion and Zynga brought a lot of real life cars to the table for CSR Racing 2. From souped up everyday rides made by Nissan and Hyundai to supercars produced by the likes of McLaren and Pagani, there really is something for everyone. [... | Read more »
Crypt of the NecroDancer Pocket Edition...
Crypt of the NecroDancer Pocket Edition 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Crypt of the NecroDancer is an award winning hardcore roguelike rhythm game. Move to the music and... | Read more »
Gear-grinding puzzle title Inner Circle...
If you saw our post earlier this month announcing the imminent release of ZPlay’s new creation, Inner Circle, you’ll be happy to know that it’s now available on the App Store. Established in 2010, developer and publisher ZPlay have taken the... | Read more »
CSR Racing 2: Your guide to what's...
CSR Racing 2, or CSR2, as it likes to call itself, has finally arrived. The follow-up to the immensely popular drag racing game CSR Racing is the first release from NaturalMotion since the studio's acquisition by Zynga in early 2014. [Read more] | Read more »
Nanuleu (Games)
Nanuleu 1.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1 (iTunes) Description: Nanuleu is a strategy game where you take control of ancient magical trees that protect the land from an invading dark force. A... | Read more »

Price Scanner via MacPrices.net

July 4th sale: $100 off 13-inch MacBook Airs
Amazon has 13″ MacBook Airs on sale for $100 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $899.99 $100 off MSRP - 13″ 1.6GHz/256GB MacBook Air (sku... Read more
Swiftpoint Launches Advanced Pivot, Tilt And...
Christchurch, New Zealand based Swiftpoint has announced the launch of its new generation computer mouse, The Z, on the crowdfunding website kickstarter.com. The company’s previous device, the... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
12-inch MacBooks available with free bundles...
Adorama has 12″ Retina MacBooks available including free shipping plus NY & NJ sales tax only. For a limited time, Adorama will include a free Apple USB-C to USB Adapter, free 4-Port USB Hub, and... Read more
Das Keyboard Unveils First Cloud-Connected Ke...
Austin, Texas based Das Keyboard has unveiled the newest addition to its family of high-performance mechanical keyboards with the introduction of the Das Keyboard 5Q on Kickstarter. Built with... Read more
13-inch 2.7GHz Retina MacBook Pros on sale fo...
Adorama has 13″ 2.7GHz Retina MacBook Pros on sale for up to $130 off MSRP. Shipping is free, and Adorama charges NY & NJ sales tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1169 $130 off -... Read more
New App Reminds Us to Put Down Our Phones and...
Mode, a new smartphone app that makes us more mindful of how we use our devices, debuts in the app stores today. The Mode app tracks time spent in different modes of day-to-day life without... Read more
ZuumSpeed Personalized Speedometer + HUD For...
RMKapps has announced the release and immediate availability of ZuumSpeed 1.0, its personalized speedometer plus heads up display for iOS devices. ZuumSpeed gives users over 18 custom fonts available... Read more
Apple refurbished clearance 15-inch Retina Ma...
Apple has Certified Refurbished 2014 15″ 2.2GHz Retina MacBook Pros available for $1609, $390 off original MSRP. Apple’s one-year warranty is included, and shipping is free. They have refurbished 15... Read more
9-inch 128GB Silver iPad Pro on sale for $50...
B&H Photo has the 9.7″ 128GB Silver Apple iPad Pro on sale for $699 including free shipping plus NY tax only. Their price is $50 off MSRP. Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Retail - Multiple Positions, Fort Wo...
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
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.