TweetFollow Us on Twitter

XCMD Libraries
Volume Number:5
Issue Number:6
Column Tag:HyperChat™

XCMD Corner: XCMD Libraries

By Donald Koscheka, Arthur Young & Co., MacTutor Contributing Editor

Modularity and Coupling

As you to explore XCMDs, you should continue to discover new and interesting properties of these routines. Two properties are particularly noteworthy because they lead to code that is usable outside of Hypercard. They are strong modularity and weak coupling.

You determine the modularity of a routine by counting the number of tasks it performs. Strongly modular routines handle one task. If you were writing a spreadsheet program, you would most likely separate the routine that calculates the value of a cell from the routine that displays that value. Combining these functions results in weak modularity. Weakly modular code is hard to debug because you can easily lose track of what the routine is doing at a given point.

Coupling describes how the program interacts with the outside world. Weakly coupled routines operate only on data passed as formal parameters. Weak coupling eliminates harmful side-effects caused by relying on global memory. Weakly coupled programs force you to think over how and when to pass data back and forth.

Well written XCMDs exhibit both strong modularity and weak coupling. Most XCMDs perform one task (strongly modular XCMDs), typically to add a missing feature to Hypertalk. XCMDs interface to Hypertalk using a very strict protocol, passing parameters via the command block record. This protocol coerces weakly coupling in your code.

Software Breadboard

Strong modularity and weak coupling suggest that you can create libraries of useful routines for use both in Hypercard and in programs of your own design. Think of Hypercard as a “Software Breadboard”, a test platform that you plug code into for checkout and debugging. Once working, the routine can be dropped into any application.

An example of a set of routines that play well in this scenario are the calls to the File Manager. Every (non-trivial) application needs to call on the file manager to open a file, access information in the file and then close it. I decided to build my case around accessing a file because Hypercard itself doesn’t handle files “according to Hoyle”. Hypercard violates two precepts of the user interface guidelines when opening a file: (1) The user is required to know the full pathname of a file if it is not in the current working directory and (2) the OpenFile command performs an unexpected action; if it cannot find the file, it creates it!

In order to properly open a file, you first present the user with a dialog that contains the list of files in the current working directory. This dialog allows the user to flip from drive to drive as well as change directories. The standard file package provides you with the “vanilla” get file dialog. When the user selects a file and clicks the “Open” button, your code queries the reply record to discover the file’s name, working directory id and file type.

The working directory id pinpoints which folder contains the document. If you made a killing on Macintosh software and have been away on some deserted island for the past several years, the working directory assumes the role traditionally held by the volume reference number.

Given the file name and working directory, you can reconstruct and return the full pathname to Hypercard so that it can be used by Hypercard’s “open” command (pathname reconstruction is the subject of a future article). However, it’s just as easy to open the file ourselves to ensure that it opens in whatever manner is expected on the Macintosh. The XCMD that opens the file is left as an exercise.

GetFileName XFCN

The XFCN, GetFileName (Listing 1), displays strong modularity - its sole task is to get the name of a file from the user. By relying only on data passed to it formally, it also demonstrates weak coupling. This XFCN provides a general purpose technique for getting the name of a file from the user. GetFileName calls on a routine Called GetFileNametoLoad in HyperUtils.c (listing 2). The prototypes for HyperUtils are found in HyperUtils.h (listing 3). HyperUtils contains a set of re-usable utilities that do not presume the existence of Hypertalk. These routines aren’t encumbered with the XCmdBlkPtr interface.

GetFileNameToLoad accepts as its inputs a list of file types (up to 4) to filter out in the open dialog. If you were writing a text import routine, you might want to present the user with only files of type ‘TEXT’. From Hypercard, you would then invoke GetFileName as:

--1

 Put GetFileName( “TEXT” ) into it;  IF it is not empty then -- User 
selected a file  put item 1 of it into FileName          put item 2 of 
it into FolderID end if 

With little effort, we’ve created a re-usable, general purpose XCMD. Pass the name and the FolderID to any File Manager call that requires the file’s name and volume reference number (aka working directory id). I will call upon this XCMD in future editions of this column so you’ll have ample opportunity to see it action.

An obvious addition to this list an xcmd that asks the user for the name of a file to save by calling SFPutFile. This is a simple modification to GetFileNameToLoad so I’ll leave it as yet another exercise.

After creating enough XCMDs, you’ll soon view them as general purpose routines with a specific interface (XCmdBlkPtr) to HyperTalk. With this in mind, you should have no trouble creating XCMD libraries that can be used in other applications. Get in the habit of separating the Hypertalk interface, including any callbacks, from the action code. The XCMD itself then becomes an interface between HyperTalk and your code.

Listing 1:  GetFileName.c
/********************************/
/* File: GetFileName.c    */
/* */
/* Using Standard File Package*/
/* query the user for the name*/
/* of a file to open, and return*/
/* the name along with the  */
/* working directory id of the*/
/* file.*/
/* Paramters:    */
/* paramCnt = number of types */
/* params[0..3] = the types to   */
/* filter for (see Inside Mac.*/
/* I-523 for details */ 
/* ----------------------------  */
/* To Build:*/
/* (1) Create a project using */
/* this file as well as the */
/* XCMD.Glue.c file. (Set */
/* project type to XCMD (or */
/* XFCN) from the Project menu.  */
/* */
/* (2) Bring the project up to*/
/* date.*/
/* (3) Build Code Resource. */
/* (4) Use ResEdit to copy the   */
/* resource to your stack.*/
/********************************/

#include<MacTypes.h>
#include<OSUtil.h>
#include<MemoryMgr.h>
#include<FileMgr.h>
#include<ResourceMgr.h>
#include<pascal.h>
#include<strings.h>
#include  “HyperXCmd.h”
#include“HyperUtils.h”

pascal void main( paramPtr )
 XCmdBlockPtr  paramPtr;
{
 short  FileWDID;
 short  numTypes;
 short  i;
 SFTypeList typs;
 char   FileName[256];
 char   WDIDString[32];
 char   comma[2];
 
 if( !paramPtr->paramCount )
 numTypes = -1;  /* select all since no type specified */
 else{
 numTypes = paramPtr->paramCount;
 for( i = 0; i < numTypes; i++ )
 BlockMove( *(paramPtr->params[i]), &typs[i], 4L );
 }
 
 *FileName = ‘\0’;
 
 if( GetFileNameToOpen( typs, numTypes, FileName, &FileWDID ) ){
 NumToStr( paramPtr, (long)FileWDID, &WDIDString );
 PtoCstr( WDIDString );
 
 comma[0] = ‘,’; /* for you MPW folk */
 comma[1] = ‘\0’;
 
 strcat( FileName, comma );
 strcat( FileName, WDIDString );
 CtoPstr( FileName );
 }
 paramPtr->returnValue = PasToZero( paramPtr, FileName );
}
Listing 2:  HyperUtils.c

/****************************/
/* HyperUtils.c  */
/* A collection of useful */
/* routines...   */
/****************************/
#include<MacTypes.h>
#include<OSUtil.h>
#include<MemoryMgr.h>
#include<FileMgr.h>
#include<ResourceMgr.h>
#include<StdFilePkg.h>
#include  “HyperXCmd.h”
#include  “HyperUtils.h”

void  CenterWindow( wptr )
 WindowPtrwptr;
/***************************
* Center a window in the current
* screen port.  Note: Does not
* attempt to work with multi-screen
* systems.
*
* This code is inspired by a
* similar routine written by Steve
* Maller in MPW Pascal.  Thanks Steve.
***************************/
{
 short  hWindSize = wptr->portRect.right - wptr->portRect.left;
 short  vWindSize = wptr->portRect.bottom - wptr->portRect.top;
 short  hSize = wptr->portBits.bounds.right - wptr->portBits.bounds.left;
 short  vSize = wptr->portBits.bounds.bottom - wptr->portBits.bounds.top;
 
 MoveWindow( wptr, 
 ( hSize - hWindSize ) / 2, 
 ( vSize - vWindSize + 20) / 2,
 false
 );
}

void Concat( str1, str2 )
 char *str1;
 char *str2;
/*****************************
* Append string 2 to the end of
* string 1.  Both strings are 
* pascal-format strings.
*
* str1 must be large enough to hold
* the new string and is assumed to 
* be of Type Str255 (a pascal string)
*****************************/
{
 short len1 = *str1; /***number of chars in str 1***/
 short len2 = *str2++;/***number of chars in str 2***/
 char  *temp;  /*** string pointer ***/
 
 *str1 += len2 + 1;/*** add sizes to get new size***/

 temp = str1 + len1 + 1;/*** move to end of str 1***/
 while( len2 ){
 *temp++ = *str2++;/*** add char to temp & move***/
 --len2;/*** until all characters are added***/
 }

}

void  CopyPStr( pStr1, pStr2 )
 char *pStr1;
 char *pStr2;
/****************************
* Copy the contents of pstr1 into
* pstr2.  The strings are assumed 
* to be of type STR255 (length byte
* precedes data 
*
****************************/
{short  i;
 char *tstr;
 
 tstr = pStr2;
 
 for( i = 0; i <= *pStr1; i++ )
 *tstr++ = *pStr1++;
}

short GetFileNameToOpen( typs, typCnt,theName, theWDID )
 SFTypeList typs;
 short  typCnt;
 char   *theName;
 short  *theWDID;
/*****************************
* Invokes SFOpenFile to query the 
* user for the name of a file to 
* open. 
*
* In:   List of types of files to
*filter for (up to 4)
* Out:  fileName if picked in theName
*working directory in theWDID
*nil otherwise
*the file’s volum ref num.
* ( Note that the space for the 
* string must be allocated by the
* caller).
*****************************/
{
 Point  where;
 char   prompt[1];
 SFReplyreply;
 GrafPort *oldPort;
 WindowPtrdlogID;
 
 prompt[0]  = ‘\0’;
 
 /*** Get and put up the standard file ***/
 /*** dialog.  You will only see the file***/
 /*** types that you filtered for.  If ***/
 /*** you filtered for no files, then  ***/
 /*** all files will display***/
 
 GetPort( &oldPort );
 dlogID = GetNewDialog( (short)getDlgID, (Ptr)NIL, (Ptr)UPFRONT );
 
 SetPort( dlogID );
 CenterWindow( dlogID );
 where.h = dlogID->portRect.left;
 where.v = dlogID->portRect.top;
 LocalToGlobal( &where );
 
 SFGetFile( where, prompt, (Ptr)NIL, typCnt, typs, (Ptr)NIL, &reply );
 
 DisposDialog( dlogID );
 SetPort( oldPort );
 
 /*** If the user selected a file, let’s ***/
 /*** get the information about it ***/
 
 if (reply.good){
 *theWDID = reply.vRefNum;
 PtoCstr( (char *)&reply.fName );
 strcpy( theName, &reply.fName  );
 }
 return( reply.good );
}
Listing 3:  HyperUtils.H

/********************************/
/* HyperUtils.H  */
/* Header file for HyperUtils.c  */
/* routines...   */
/********************************/

#define NIL 0L
#define UPFRONT  -1L

void  CenterWindow( WindowPtr wptr );
void  Concat( char * str1, char * str2 );
void  CopyPStr( char * pStr1, char * pStr2 );
short GetFileNameToOpen(SFTypeList typs,short typcnt, char *theName, 
short *theWDID);

NOTE: From Jul 89 Jorg Column

Note on a bug in last month’s article:

Last month’s XFCN, GetFileName, incorrectly returns the working directory id of the file selected from SFGetFile. Change the call to GetFileNameToOpen to Read:

if( GetFileNameToOpen(typs,numTypes,FileName,&FileWDID ) ){
 temp = (long)FileWDID & 0xFFFF;
 NumToStr( paramPtr, temp, &WDIDString );
 PtoCstr( WDIDString );

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Final Cut Pro X 10.4 - Professional vide...
Final Cut Pro X is a professional video editing solution. Completely redesigned from the ground up, Final Cut Pro adds extraordinary speed, quality, and flexibility to every part of the post-... Read more
Motion 5.4 - Create and customize Final...
Motion is designed for video editors, Motion 5 lets you customize Final Cut Pro titles, transitions, and effects. Or create your own dazzling animations in 2D or 3D space, with real-time feedback as... Read more
Logic Pro X 10.3.3 - Music creation and...
Logic Pro X is the most advanced version of Logic ever. Sophisticated new tools for professional songwriting, editing, and mixing are built around a modern interface that's designed to get creative... Read more
Compressor 4.4 - Adds power and flexibil...
Compressor adds power and flexibility to Final Cut Pro X export. Customize output settings, work faster with distributed encoding, and tap into a comprehensive set of delivery features. Features... Read more
Drive Genius 5.1.0 - $99.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
Microsoft Office 2016 15.41 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
iExplorer 4.1.13 - View and transfer fil...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
Civilization VI 1.0.6 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
Data Rescue 5.0.3 - Powerful hard drive...
Data Rescue’s new and improved features let you scan, search, and recover your files faster than ever before. We have modernized the file-preview capabilities, added new files types to the recovery... Read more
Civilization VI 1.0.6 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more

Latest Forum Discussions

See All

The 5 best Star Wars games on iOS
The time has almost come.Star Wars: The Last Jedifinally hits theaters in the cinematic event that might be bigger than Christmas. To celebrate, we're taking a look at the best--and only the best--Star Warsmobile games to date. [Read more] | Read more »
Life Is Strange (Games)
Life Is Strange 1.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1 (iTunes) Description: Life Is Strange is a five part episodic game that sets out to revolutionize story-based choice and consequence games by... | Read more »
Oddworld: New 'n' Tasty (Game...
Oddworld: New 'n' Tasty 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: ** PLEASE NOTE: Requires 3.6GB free space to install. Runs at variable resolutions based on device capabilities.... | Read more »
Gorogoa (Games)
Gorogoa 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Gorogoa is an elegant evolution of the puzzle genre, told through a beautifully hand-drawn story designed and illustrated by Jason... | Read more »
Why Guns of Boom will be big for mobile...
Earlier this week, Game Insight, the minds that brought you Guns of Boom, revealed plans for an esports mode in the popular FPS title, with big implications for the game's future. Guns of Boom has been quite popular for some time now, so it's... | Read more »
Rules of Survival guide - how to boost y...
It's not easy surviving in the "every-man-for-himself" world of Rules of Survival. You'll be facing off against many other players who might be more skilled than you, or are luckier than you. There are a lot of factors weighing against you. With... | Read more »
FEZ Pocket Edition (Games)
FEZ Pocket Edition 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Amazing Katamari Damacy guide - beginner...
Amazing Katamari Damacy brings the bizarro world of the original games to mobile and shifts them into an endless format that's just as addictive as the PlayStation entries. Your goal is still to roll as much random stuff as you possibly can, though... | Read more »
Portal Knights guide - crafting tips and...
In Portal Knights, you're only as strong as the items you have at your disposal. This sandbox adventure is all about crafting and building up the next big thing. Whether you're an avid explorer or collector, crafting will likely play a large part... | Read more »
The best deals on the App Store this wee...
A new week means new discounts on the App Store. This week's deals run the gamut of action-adventure titles, puzzle games, and one of the best narrative adventure series out there. If you're looking to fill out your mobile gaming library on a... | Read more »

Price Scanner via MacPrices.net

Beats Holiday sale at B&H, headphones and...
B&H Photo has Beats by Dr. Dre headphones, earphones, and speakers on sale for up to $80 off MSRP as part of their Holiday sale. Expedited shipping is free, and B&H charges sales tax to NY... Read more
Holiday sale: Apple resellers offer 2017 15″...
MacMall has 15″ MacBook Pros on sale for $220-$300 off MSRP, each including free shipping: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2179, $220 off MSRP – 15″ 2.8GHz MacBook Pro Silver (... Read more
Holiday sale: Apple resellers offer 13″ MacBo...
B&H Photo has 13″ MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13-inch 2.3GHz/128GB Space Gray MacBook Pro (... Read more
Apple Watch Series 2, Certified Refurbished,...
Apple has Certified Refurbished Apple Watch Nike+ Series 2s, 42mm Space Gray Aluminum Case with Anthracite/Black Nike Sport Bands, available for $249 (38mm) or $279 (42mm). The 38mm model was out of... Read more
Apple offers Certified Refurbished 2016 12″ R...
Apple has Certified Refurbished 2016 12″ Retina MacBooks available starting at $949. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
B&H drops price on 13″ 256GB MacBook Air...
B&H has the 13″ 1.8GHz/256GB Apple MacBook Air (MQD42LL/A) now on sale for $1079 including free shipping plus NY & NJ sales tax only. Their price is $120 off MSRP, and it’s the lowest price... Read more
Holiday sale: 9″ iPads starting at $299, take...
MacMall has 9″ WiFi iPads on sale for $30 off including free shipping: – 9″ 32GB WiFi iPad: $299 – 9″ 128GB WiFi iPad: $399 Read more
Green Monday deal: 15″ 2.8GHz MacBook Pro on...
B&H Photo has the 15″ 2.8GHz Space Gray MacBook Pro on sale for $250 off MSRP for today only as part of their Green Monday/Holiday sale. Shipping is free, and B&H charges sales tax for NY... Read more
Green Monday sale: B&H offers 12″ Apple i...
B&H Photo has 12″ iPad Pros on sale for up to $150 off MSRP as part of their Green Monday/Holiday sale. Shipping is free, and B&H charges sales tax in NY & NJ only: – 12″ 64GB WiFi iPad... Read more
Holiday deal: 21″ and 27″ Apple iMacs on sale...
MacMall has 2017 21″ and 27″ Apple iMacs on sale for up to $200 off MSRP. Shipping is free: – 21″ 2.3GHz iMac: $999 $100 off MSRP – 21″ 3.0GHz iMac: $1199 $100 off MSRP – 21″ 3.4GHz iMac: $1379 $120... Read more

Jobs Board

*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 113124408 Waterford, CT, Connecticut, United States Posted: 17-Oct-2017 Weekly Hours: 40.00 **Job Summary** Are you Read more
QA Automation Engineer, *Apple* Pay - Apple...
# QA Automation Engineer, Apple Pay Job Number: 113202642 Santa Clara Valley, California, United States Posted: 11-Dec-2017 Weekly Hours: 40.00 **Job Summary** At Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, 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* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.