DateSelectorGadClass ~~~~~~~~~~~~~~~~~~~~ Release: 1.1 (05.06.1993) Author: Markus Aalto COPYRIGHT ~~~~~~~~~ DateSelectorGadClass BOOPSI object for AmigaDOS V37 or greater. Copyright (C) 1993 Markus Aalto This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. You can contact me by writing to Markus Aalto, Muurahaisentie 11a, 01490 VANTAA, FINLAND. Or send EMail to s37732v@vipunen.hut.fi. INTRODUCTION ~~~~~~~~~~~~ This is a documentation for DateSelector gadget class. This gadget class is implemented as a subclass of "gadgetclass" BOOPSI class. Therefore it inherits all the qualities of its parent making it therefore a very flexible and easy to use gadget class. DateSelector gadget is like a group of buttons from which an user can select a date. It is quite flexible in allowing programmer to control the appearance of the gadget group. But more of it later. FUNCTION ~~~~~~~~ DateSelectorGadClass link-time library consists of 3 public functions user can call. These are explained in detail in DateSelectorGadClass.doc, but I represent them here for clarity. initDateSelectorGadClass() function is used to create a private subclass from 'gadgetclass'. It returns pointer to this new class, so that user can use it to create BOOPSI objects with NewObject() (see intuition.library documentation). freeDateSelectorGadClass() is the function user have to call to free the resources allocated by initDateSelectorGadClass(). Call it when you are done using DateSelectorGadClass. And finally there is a DateSelectorGadDimensions() which calculates the optimal size for the gadget. This should always be called before creating a new gadget with NewObject(), so that user would get the best possible size for the object. See more about this from 'DateSelectorGadget Dimensions'. TAGS ~~~~ The tags recognized by the DateSelector gadget class are. DSG_YEAR (UWORD) Set this value to the year you are currently modifying. This is necessary because DateSelectorGadget has to know whether is it a leap year or not. Also when you are not using FIXED position then it's very important that this is correctly set. Acceptable values go from 1978 to 2099. Default is 1978. (Create, Set and Get). DSG_MONTH (UWORD) Current month. This is also very important to set. DateSelectorGadget needs to know the month, so that (1.) it can draw right number of buttons and (2.) knows how to position the buttons if DSG_FIXEDPOSITION is not enabled. Acceptable values go from 1 to 12. Default is 1. (Create, Set and Get). DSG_DAY (UWORD) Current Day. This is the current active day in DateSelectorGadget. Acceptable values go from 1 to 28-31. According to the month. If day is too large number for this month, then it is converted to largest possible date in this month. Default is 1. (Create, Set and Get). DSG_TEXTFONT (struct TextFont *) Pointer to TextFont structure. You have to set this to make proper rendering possible. This should be exactly the same pointer you pass to DateSelectorGadDimensions() function. Setting this to NULL can easily generate some fireworks. (Create). DSG_FIXEDPOSITION (BOOL) Set this attribute if you want to make buttons start from the 1st position (upper-left corner). Otherwise if for example first day in the month is Tuesday then buttons start from the 2nd position. If it's Thursday then buttons start from the 4th position and so on. Default is TRUE. (Create). DSG_SUNDAYFIRST (BOOL) Some countries (USA, ... ?) use Sunday as the first day in a week. If you want to use non-fixed button positions and you want sunday to be used in a leftmost position then you have to enable this. Users of V38 (or greater) could use Locale system to check users preferred method. This attribute is used only if DSG_FIXEDPOSITION is disabled. Default is FALSE. (Create). GA_Disabled (BOOL) Set this attribute to TRUE to disable DateSelector, to FALSE otherwise. Default is FALSE. (Create and Set). DATESELECTORGADGET DIMENSIONS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You should use DateSelectorGadDimensions() function to obtain the right dimensions for your gadget, but I'll explain here the method which is used to calculate it. 1. We calculate the widest number in pixels (from 1 to 31), and add 8 pixels for borders and nice look. 2. Get the font height and add 4 pixels for borders. Now we have a size of one button. 3. The width of the whole group can then be calculated by multiplying the width of one button with 7. 4. If your gadget uses DSG_FIXEDPOSITION then height is 5 times the height of one button. Otherwise it's 6 times the height of one button. 5. Ready! So if you are using non-proportional topaz 8 font. Then widest number is 16 pixels wide. So 1 button is 16+8 = 24 pixels wide. It's also 8+4 = 12 pixels high. So with DSG_FIXEDPOSITION enabled DateSelectorGadget would be 168*60 pixels. You can also give default dimensions for DateSelectorGadDimensions(). It changes them so that they are as close as possible to the values you specified but still conform to the guidelines. NOTES ~~~~~ When you attach DateSelectorGadget to the window, make sure that IDCMP_IDCMPUPDATE flag is set if you want to hear when user changes date values. The tagitem list sent in IntuiMessage's IAddress field contains GA_ID, DSG_DAY, DSG_MONTH and DSG_YEAR tags. So you can identify it from GA_ID tag and get the value from DSG_DAY, ... tags. Obey the dimensions DateSelectorGadDimensions gives you. This gives you best looking visuals. If you want to add more width to buttons then always add multiples of seven. DateSelectorGadClass.lib needs following libraries to be open: graphics.library, intuition.library and utility.library. All version 37 or greater of course. If SetGadgetAttrs() returns anything else than 0 (when setting atrributes for DateSelector gadget) you should try to check date values with GetGadgetAttrs(). If you disable DSG_FIXEDPOSITION mode you should add a row of day names ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun") over the DateSelector gadget. In this way user gets to see 'Time Preferences' like date selector. See example2 how to do it. If you use gadget's ID value to identify your DateSelector gadget then do not let other Boopsi gadgets send GA_ID messages to your gadget. You can prevent this by using Map tags and mapping GA_ID to TAG_IGNORE. Example2 uses this method. HISTORY ~~~~~~~ 1.0 / 06-Apr-1993 Supports YEAR, MONTH, DAY, FIXEDPOSITION and SUNDAYFIRST tags. ------------------------------------------------------------------- 1.1 / 05-Jun-1993 Supports optimized rendering when DSG_FIXEDPOSITION is enabled. Fixed a (harmless?) bug in handling of OPUF_INTERIM messages. -------------------------------------------------------------------