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

VOX 2.8.30 - Music player that supports...
VOX just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all audio formats you should ever need.... Read more
Default Folder X 5.1.6b3 - 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 on... Read more
CleanMyMac 3.8.6 - $39.95
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac lets you safely and intelligently scan and clean your entire system, delete large, unused files... Read more
Postbox 5.0.17 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
Amazon Chime 4.6.5852 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
coconutBattery 3.6.3 - Displays info abo...
With coconutBattery you're always aware of your current battery health. It shows you live information about your battery such as how often it was charged and how is the current maximum capacity in... Read more
VueScan 9.5.82 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Thunderbird 52.3.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Little Snitch 4.0.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
Thunderbird 52.3.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more

The best games we played this week - Aug...
Another busy week has come to a close. We played a lot of excellent games this week and now it's time to look back and reflect on some our favorites. Here are our picks for the week of August 18. [Read more] | Read more »
War Wings beginner's guide - how to...
War Wings is the newest project from well-established game maker Miniclip. It's a World War II aerial dogfighting game with loads of different airplane models to unlock and battle. The game offers plenty of single player and multiplayer action. We... | Read more »
How to win every 2v2 battle in Clash Roy...
2v2 is coming back to Clash Royale in a big way. Although it's only been available for temporary periods of time, 2v2 has seen a hugely positive fan response, with players clamoring for more team-based gameplay. Soon we'll get yet another taste of... | Read more »
Roll to Win with Game of Dice’s new upda...
Joycity’s hit Game of Dice gets a big new update this week, introducing new maps, mechanics, and even costumes. The update sets players loose on an exciting new map, The Cursed Tower, that allows folks to use special Runes mid-match. If you feel... | Read more »
Bottom of the 9th (Games)
Bottom of the 9th 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Play the most exciting moment of baseball in this fast-paced dice and card game! | Read more »
The best apps for viewing the solar ecli...
If you somehow missed the news, many parts of the United States will be witness to a total solar eclipse on August 21 for the first time in over 90 years. It'll be possible to see the eclipse in at least some capacity throughout the continental U... | Read more »
The 5 best mobile survival games
Games like ARK: Survival Evolved and Conan Exiles have taken the world of gaming by storm. The market is now flooded with hardcore survival games that send players off into the game's world with nothing but maybe the clothes on their back. Never... | Read more »
Portal Walk (Games)
Portal Walk 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Portal Walk is adventure and relaxing platform game about Eugene. Eugene stuck between worlds and trying to find way back home.... | Read more »
Technobabylon (Games)
Technobabylon 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: City of Newton, 2087. Genetic engineering is the norm, the addictive Trance has replaced almost any need for human interaction,... | Read more »
5 reasons why 2v2 is the best mode in Cl...
Supercell has been teasing fans with 2v2 windows that allow players to team up for limited periods of time. The Summer of 2v2 was just this past July, but players are already clamoring for more of that sweet, sweet team-based action. The fans have... | Read more »

Price Scanner via MacPrices.net

Back To School With The Edge Desk All-in-one...
Back to school is just around the corner, and the ergonomically correct Edge Desk all-in-one portable kneeling desk is ideal for students living in dorms and small apartments, Edge Desk features:... Read more
Norton Core Secure Wi-Fi Router Now Available...
First introduced at the 2017 Consumer Electronics Show (CES), Norton Core, a secure, high-performance Wi-Fi router, fundamentally changed the concept of Wi-Fi routers by making security the primary... Read more
ViewSonic Adds New 27-inch 4K UHD Monitor to...
ViewSonic Corp. has introduced the VP2785-4K, a 27-inch 4K UHD (3840×2160) monitor that delivers precise and consistent color representation and performance to ensure incredible image quality. Built... Read more
Apple now offering Certified Refurbished 2017...
Apple is now offering Certified Refurbished 2017 27″ iMacs for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27″ 3.... Read more
13-inch 2.3GHz MacBook Pros on sale for $100...
Amazon has the new 2017 13″ 2.3GHz MacBook Pros on sale today for $100 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A): $1199.99 $100 off MSRP – 13″ 2.... Read more
Clearance 2016 13-inch MacBook Airs available...
B&H Photo has clearance 2016 13″ MacBook Airs available for up to $200 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 13″ 1.6GHz/128GB MacBook Air (MMGF2LL... Read more
Clearance 21-inch and 27-inch iMacs available...
B&H Photo has clearance 21″ and 27″ Apple iMacs available for up to $500 off original MSRP, each including free shipping plus NY & NJ sales tax only: – 27″ 3.3GHz iMac 5K: $1799 $500 off... Read more
New iOS 11 Productivity Features Welcome But...
The iOS community is in late summer holding mode awaiting the September arrival of the iPhone 8 and iOS 11. iOS 11 public betas have been available for months — number six was released this week —... Read more
Samsung Electronics Launches New Portable SSD...
Samsung Electronics America, Inc. has announced the launch of Samsung Portable SSD T5 – its newest portable solid state drive (PSSD) that raises the bar for the performance of external memory... Read more
TrendForce Reports YoY Gain of 3.6% for 2Q17...
Market research firm TrendForce reports that the global notebook shipments for this second quarter registered a sequential quarterly increase of 5.7% and a year-on-year increase of 3.6%, totaling 39.... Read more

Jobs Board

Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Business Development Manager - *Apple* Medi...
Job Summary Apple Music is a single, intuitive app that...- all in one place. You can stream any Apple Music song, playlist or album, and download it Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.