TweetFollow Us on Twitter

September 30 - UDates

UDates

Jesse Feiler, The Philmont Software Mill

Who am I to argue with a cute, curly-haired orphan, but… Annie was wrong. "Tomorrow, tomorrow, I love ya, tomorrow, you're only a day away" she sang (and at the slightest provocation).

To those of us who have worked on systems that are time-sensitive, we know that "tomorrow" is only sometimes a day away. For example:

  • in most businesses, the "tomorrow" of Friday is Monday
  • similarly, the "tomorrow" of December 24 is December 26 (unless a weekend intervenes, or Boxing Day is a holiday, as in England [and in Canada: Ed.]).
  • and, if you are editing a transaction that was entered days ago in order to fix a typo, you may be processing data as of last week, and the system's idea of "tomorrow" is actually a week ago.

The code to handle all of this is not particularly obscure, and many of us have written it-over and over and over again.

From the earliest days on the Mac, we have had very good date and time manipulation routines available in the toolbox. Recently, the Script Manager incorporated some rather nifty text-parsing routines that it combines with new date routines to make everything transparent, whether you are in Japan or Egypt, and whether you are interested in this era or in one distant by several millennia.

I decided that once and for all I would take the toolbox routines and combine them into some MacApp objects that could be used (and overridden) for almost any purpose involving date manipulation. And thus was the UDates unit born.

From a user's point of view, the two most important objects in UDates are the TDateCluster and the TElapsedTimeCluster. Both are descendants of TCluster and are designed to be placed in TDialogViews.

Here's a step-by-step description of their behavior. Note that both are initialized to a "today" date which will be described later. In addition, assume that Saturday and Sunday are weekends, although UDates allows you to specify any weekend days that you want.

TDateCluster

Now, as you might expect, the two boxes at the left are editable. In fact, they belong to a class called TDateEditText which is a descendant of TEditText. TDateEditText objects are basically TEditTexts but with the added functionality that their Validate methods expect the contents to be a date which is parsable by the Script Manager routines. If the date doesn't pass the Script Manager parsing, Validate fails and MacApp restores the previous value. The programmer can thus always assume that there's a valid date in a TDateEditText.

Finally, the TDateCluster provides the information as to whether the date values it returns are the result of user data entry or of clicking on the radio buttons. In some cases, the program is only interested in the start and stop dates shown in the TDateCluster. In other cases, it is important to know whether the user is after this week's data (regardless of date) or the data for 3/12 – 3/16 specifically.

Here's the interface to TDateCluster:

TDateCluster = OBJECT (TCluster)
fDateObj: TDateObj;         {a TDateObj, probably set to today}
fFrom, fTo: TDateEditText;  {private - use GetStartStop}

FUNCTION TDateCluster.GetStartStop(
                                    VAR d1, d2: LongDateTime;
                                    VAR rChoice: IDType): BOOLEAN;
PROCEDURE TDateCluster.IDateCluster(aDate: TDateObj);
PROCEDURE TDateCluster.DoChoice(
                                    origView: TView; 
                                    itsChoice: INTEGER); OVERRIDE;
PROCEDURE TDateCluster.Fields(PROCEDURE DoToField(
                                    fieldName: STR255;
                                    feldAddr: Ptr;
                                    fieldType: INTEGER)); OVERRIDE;
PROCEDURE TDateCluster.Free; OVERRIDE;
END;

Only IDateCluster and GetStartStop are normally used.

TElapsedTimeCluster

The TElapsedTimeCluster consists of three editable fields: two date-time fields, and one field which represents the number of hours between the two date-times. Thus, after posing the TElapsedTimeCluster in the DateSample program, you can enter 1.5 in the elapsed time field… and after any other event in the dialog, the second date-time field will be adjusted. The TElapsedTimeCluster will take whatever two fields are entered and calculate the third.

{IElapsedTimeCluster can handle a 0 for d2 (stop time) and/or duration. If duration is 0, it is calculated. If d2 (stop time) is 0, it is calculated using duration. You might want to do your own error-checking to make sure that you are passing in good values. TElapsedTimeCluster makes sure that all three fields are consistent: change fFrom or fTo, and fDuration is updated. Change fDuration and fTo is changed. (Yes, it could have been coded the other way, but it wasn't. If you want duration to count backwards from fTo and modify fFrom, modify the object.) GetStartStop gives you the start and stop times.}

Here is the interface to TElapsedTimeCluster:

TElapsedTimeCluster = OBJECT (TCluster)

fDateObj:   TDateObj;           {probably today}
fFrom, fTo: TValDateEditText;   {private - use StartStop}
fDuration:  TValEditText;       {private - use GetStartStop}

PROCEDURE TElapsedTimeCluster.Free; OVERRIDE;
FUNCTION TElapsedTimeCluster.GetStartStop( 
                                    VAR  d1,d2:LongDateTime):BOOLEAN;
PROCEDURE TElapsedTimeCluster.IElapsedTimeCluster(
                                    aDate: TDateObj; 
                                    d1,d2: LongDateTime;
                                    duration: comp;
                                    aStyle: TextStyle);
FUNCTION TElapsedTimeCluster.Validate:LONGINT; OVERRIDE;
PROCEDURE TElapsedTimeCluster.Fields(PROCEDUREDoToField(
                                    fieldName:STR255;
                                    fieldAddr: Ptr;
                                    FieldType:INTEGER)); OVERRIDE;
END;

Again, GetStartStop and IElapsedTimeCluster are likely to be the only methods which you'll call directly. Validate is called for you by TDialogView, but nothing prevents you from calling it yourself at some other time.

TDateEditText

In the DateSample program, the Set "today" dialog allows you not only to set the "today," but also to experiment with a TDateEditText field. Typing in "12" sets the date to March 12, 1990, since the Script Manager defaults to current month and current year. The Script Manager will recognize non-standard delimiters and-as shown in a recent Tech Note-its flexibility will allow it in some circumstances to wander off in very peculiar directions. Fortunately, you can check to see how far afield the parser has gone and set your tolerance level as low or as high as you want.

{The IEditText and IRes methods initialize all fields. You may want to subsequently reset fWantDate or fWantTime. Resetting fDidEdit is undefined (polite for "stupid"). fDate is obtainable in alternate formats by calling GetLongDateTime or GetLongDateRec. }

Here's the interface to TDateEditText:

TDateEditText = OBJECT (TEditText)

fWantDate, fWantTime, fDidEdit, fZeroBlank: BOOLEAN;
fDate: LongDateRec; 

PROCEDURE TDateEditText.Fields(PROCEDURE DoToField(
                                 fieldName:STR255;
                                 fieldAddr: Ptr;
                                 FieldType: INTEGER)); OVERRIDE;
FUNCTION TDateEditText.GetLongDateTime(
                             VAR aDate: LongDateTime):BOOLEAN;
FUNCTION TDateEditText.GetLongDateRec(
                             VAR aDateRec: LongDateRec): BOOLEAN;

PROCEDURE TDateEditText.IEditText(
                                 itsSuperView: TView;
                                 itsLocation, itsSize:VPoint;
                                 itsMaxChars: INTEGER);
     OVERRIDE;
PROCEDURE TDateEditText.IRes(
                                 itsDocument: TDocument;
                                 itsSuperView: TView;
                                 VAR itsParams: Ptr); OVERRIDE;
PROCEDURE TDateEditText.SetDate(
                                 aDate: LongDateTime;
                                 reDraw: BOOLEAN);
FUNCTION TDateEditText.Validate: LONGINT; OVERRIDE;

END;

Once again, the methods shown in bold are the ones which you are likely to call directly. Note one point about IEditText: it does NOT set the initial value; you have to call SetDate. It is generally agreed that the IYourObject methods should leave all fields set to some value (e.g., handles to NIL if not actually allocated). In our recent projects we have tended to separate the setting of values from the initialization of the object. Thus, in a project that uses UDates, we have three methods that handle the fields:

  1. InstallADate (location, etc.)
  2. LoadADate (sets values)
  3. UnLoadADate (gets values)

Similar triplets of methods are used for other types of data entry fields. This works very nicely for cases where one view is used to show and update data from various database records.

TDateObj

The third major object in UDates is the TDateObj. It is initialized to a given date and to the weekends and holidays which it should recognize. Thereafter, it can quickly provide yesterday, tomorrow, next week, etc. as needed. In general, one TDateObj is initialized for the application and is not reset during program execution.

The interface for TDateObj is not provided here, since it is fairly lengthy and is provided in the code which follows.

Using UDates

The objects in UDates are designed to be as basic as possible and still provide the needed functionality. They can be customized in two ways. First of all, they can of course be overridden to change their behavior. Secondly, there are parameters which can be set by the program (e.g., do you want both date and time shown in a TDateEditText field?) to modify their behavior. In general, I have assumed that the parameter setting will be fairly constant within an application, and therefore error-checking for parameters is done only in the Debug version. Both Debug and NonDebug versions should catch errors which a user might make in data entry.

In addition, the TDateCluster and TElapsedTimeCluster are views that are editable in ViewEdit to allow a developer to use a specific application's standard fonts and graphic styles. TElapsedTimeCluster is about as sparse as you can get in terms of text, because in those cases where it's been used, we have always modified the resource to incorporate additional text fields.

The code which follows is for UDates itself as well as for DateSample, a small application which uses UDates and to show the results of various commands via messages in the Debug window.

The code is (I hope) fairly clear and well-annotated, so there's no point in going through it in detail. I will, however, mention a few points which may be of interest.

Creating a new, generalized unit

All programmers, and MacApp programmers in particular, have sections of code which they reuse. In my particular repertoire are a FailDBErr routine that I use to trap Inside Out errors, a unit of utility dialogs, and of course UDates itself. In creating these units, I've found a few points to be useful:
  • Do spend a few extra moments to provide Get… and Set… routines for variables of your objects that would normally be visible to the outside world, even if that outside world is you. In TDateEditText, the GetLongDateRec and GetLongDateTime functions were the last changes made. At first it seemed silly to write these functions when the data could easily be found with the field names. The decision to add the functions was NOT made for reasons of ideological purity; it was made because some of the manipulation code was being written several times in my application.

    Whenever code is duplicated, that's a clue that it's in the wrong place and should be moved to a location where it's written once and done with. In UDates, not every variable is accessible to the outside world; providing Get… and Set… methods for all fields of an object is unnecessary (in my humble opinion). What is necessary is to decide which fields and which common transformations of them are likely to be necessary, and to provide those.

  • Don't think you save time by not having a Fields method for every object. Even if the Fields method has nothing but the object's title (bClass), it may well save you from lost time trying to figure out where you are.
  • In creating new units that you plan to reuse, take a moment to think of all possible uses of the unit. For example, we are in the process of creating a generalized numeric entry object-much like TDateEditText. That object must be a descendant of TEditText and not of TNumberText. Why? The fMinimum and fMaximum fields of TNumberText are LongInts. In addition, lots of TNumberText code assumes LongInt values.
  • Don't use standard segment names. Thus you'll find that in UDates, code is placed into $ADateRes and $ADateFields segments. The –sn option in your MAMake file will allow you to remap these segments to $ARes and $ADates if you want to. By keeping your segmentation at least temporarily separate from normal MacApp segmentation, you can easily make adjustments if you blow up a segment with the infamous >32000 error.
  • Add a local debugging option (such as qTraceDate). You'll notice that this option tracks procedure entries, sometimes printing parameters out so that you can see how things are going. Again, by using your own debugging options, you avoid interfering with MacApp and your other debuggers, so that you don't get a slew of UDates debugging messages while you're trying to debug a database problem.
  • Consider adding additional debugging code to your unit. Debugging code turns out to be (in my experience) some of the most reusable code there is. The bLongDateRec and bLongDateTime Fields options are used all through our applications.

Creating the clusters

Normally, one has a choice of creating views either from templates or programmatically. In UDates, the clusters are designed to be created ONLY from templates-and in fact the appropriate ICluster methods are missing. This is deliberate and should be considered as an advertisement for ViewEdit. The TDateCluster contains eight subviews, each of which must be placed, sized, and identified properly in order for the TDateCluster to work. In addition, the six radio buttons must be named with appropriate base names-and no one would consider hard-coding words like "Today" or "Yesterday," so those would have to be stored in a string resource. The code for doing all of this initialization is about 50 lines long. In a case like this, I do not think that template and programmatic creation are equally appropriate: ViewEdit wins hands down in such a case (even with some of its bugs-which I'm sure will be gone shortly).

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

TinkerTool 5.4 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Tinderbox 6.3.1 - Store and organize you...
Tinderbox is a personal content management assistant. It stores your notes, ideas, and plans. It can help you organize and understand them. And Tinderbox helps you share ideas through Web journals... Read more
Parallels Desktop 10.2.2 - Run Windows a...
Parallels Desktop is simply the world's bestselling, top-rated, and most trusted solution for running Windows applications on your Mac. With Parallels Desktop for Mac, you can seamlessly run both... Read more
Adobe Premiere Pro CC 2015 9.0.1 - Digit...
Premiere Pro CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Premiere Pro customer). Premiere Pro CS6 is still available for... Read more
Adobe After Effects CC 2015 13.5.1 - Cre...
After Effects CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Adobe Creative Cloud 2.2.0.129 - Access...
Adobe Creative Cloud costs $49.99/month (or less if you're a previous Creative Suite customer). Creative Suite 6 is still available for purchase (without a monthly plan) if you prefer. Introducing... Read more
Tower 2.2.3 - Version control with Git m...
Tower is a powerful Git client for OS X that makes using Git easy and more efficient. Users benefit from its elegant and comprehensive interface and a feature set that lets them enjoy the full power... Read more
Apple Java 2015-001 - For OS X 10.7, 10....
Apple Java for OS X 2015-001 installs the legacy Java 6 runtime for OS X 10.11 El Capitan, OS X 10.10 Yosemite, OS X 10.9 Mavericks, OS X 10.8 Mountain Lion, and OS X 10.7 Lion. This package is... Read more
Adobe Muse CC 2015 2015.0.1 - Design and...
Muse CC 2015 is available as part of Adobe Creative Cloud for as little as $14.99/month (or $9.99/month if you're a previous Muse customer). Muse CS6 is still available for purchase (without a... Read more
Adobe Illustrator CC 2015 19.1.0 - Profe...
Illustrator CC 2015 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Illustrator customer). Illustrator CS6 is still available for... Read more

Tap Delay (Music)
Tap Delay 1.0.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0.0 (iTunes) Description: Back in the “old days”, producers and engineers created delay and echo effects using tape machines. Tap Delay combines the warm... | Read more »
This Week at 148Apps: July 20-24, 2015
July is Heating Up With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out... | Read more »
Red Game Without A Great Name (Games)
Red Game Without A Great Name 1.0.3 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.3 (iTunes) Description: The mechanical bird is flying through an unfriendly, Steampunk world. Help it avoid obstacles and deadly... | Read more »
Warhammer: Arcane Magic (Games)
Warhammer: Arcane Magic 1.0.2 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.2 (iTunes) Description: Engage in epic battles and tactical gameplay that challenge both novice and veteran in Warhammer: Arcane Magic, a... | Read more »
Mazes of Karradash (Games)
Mazes of Karradash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: The city of Karradash is under attack: the monsters of the Shadow Realms are emerging from the depths.No adventurer is... | Read more »
Battle Golf is the Newest Game from the...
Wrassling was a pretty weird - and equally great - little wressling game. Now the developers, Folmer Kelly and Colin Lane, have turned their attention to a different sport: golfing. This is gonna be weird. [Read more] | Read more »
Qbert Rebooted has the App Store Going...
The weird little orange... whatever... is back, mostly thanks to that movie which shall remain nameless (you know the one). But anyway it's been "rebooted" and now you can play the fancy-looking Qbert Rebooted on iOS devices. [Read more] | Read more »
Giant Monsters Run Amok in The Sandbox...
So The Sandbox has just hit version number 1.99987 (seriously), and it's added a lot more stuff. Just like every other update, really. [Read more] | Read more »
Fish Pond Park (Games)
Fish Pond Park 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: Nurture an idyllic slice of tourist's heaven into the top nature spot of the nation, furnishing it with a variety of... | Read more »
Look after Baby Buddy on your Apple Watc...
Parigami Gold is the new premium version of the match three puzzler that includes Apple Watch support and all new content. You won't simply be sliding tiles around on your wrist, the Apple Watch companion app is an all new mini-game in itself. You'... | Read more »

Price Scanner via MacPrices.net

2015 13-inch 2.7GHz Retina MacBook Pro on sal...
B&H Photo has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale today for $1199 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
2.8GHz Mac mini available for $988, includes...
Adorama has the 2.8GHz Mac mini available for $988, $11 off MSRP, including a free copy of Apple’s 3-Year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax in NY & NJ... Read more
Updated Mac Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
High-Precision Battery Fuel Gauge IC Extends...
Renesas Electronics Corporation has announced its new lithium-ion (Li-ion) battery fuel gauge IC, the RAJ240500, designed to extend battery life for connected mobile devices such as tablets, notebook... Read more
27-inch 3.3GHz 5K iMac on sale for $1799, $20...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1799 including free shipping plus NY tax only. Their price is $200 off MSRP, and it’s the lowest price available for this model from any Apple... Read more
Twelve South Free Dual Screen Backgrounds Co...
Twelve South has posted a second collection of travel Desktop photos, noting: For the Twelve South team, a vacation is never just a vacation. It’s a time to try out new prototypes on the road, visit... Read more
Apple Refurbished iMacs available for up to $...
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 – $1949 $... Read more
Tablets: Why Microsoft’s Surface Is Soaring W...
In contrast to Apple’s record fiscal third quarter reported this week, Microsoft had a miserable latest quarter with its revenues falling by 5.1 percent, hammered by ongoing weak PC demand, and... Read more
Sale! 13″ 1.6GHz/256GB MacBook Air for $1099,...
B&H Photo has the 13″ 1.6GHz/256GB MacBook Air on sale for $1099 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model. Read more
iPad mini 4 To Be Upgraded To iPad Air 2 Spec...
There’s a certain inevitability about making Apple product predictions this time of year. Come September, we can pretty reliably count on the release of refreshed iPhones, along with the iOS 9... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
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 (US) - A...
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* Customer Experience (ACE) Leader - A...
…management to deliver on business objectives Training partner store staff on Apple products, services, and merchandising guidelines Coaching partner store staff on Read more
Project Manager - *Apple* Pay Security - Ap...
**Job Summary** The Apple Pay Security team is seeking a highly organized, results-driven Project Manager to drive the development of Apple Pay Security. If you are Read more
*Apple* TV Product Design Internship (Spring...
…the mechanical design effort associated with creating world-class products with the Apple TV PD Group. Responsibilities will include working closely with manufacturing, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.