	////////////////////////////////////////////////////////////
	////////////////////  kmScheduler  /////////////////////////
	////////////////////////////////////////////////////////////
	March, 2004, Ken Mayer, dBASE, Inc.
	*** I have prepared this to be used, based on the 
       most recent version of the dBASE Users' Function 
       Library Project (dUFLP), and the code therein.  
       -- March 25, 2004 --

What Is It?
-----------
This is a simple, one-user event scheduler. It's a calendar
program with the ability to add events to the calendar, 
deal with scheduling your day, etc. With some work, it
could most likely be enhanced to be a multi-user scheduler,
but I leave that up to you, the user/developer who uses
this ...

It is ALSO something that is designed to make it possible
to hook it up to your existing schedule data, and your own
scheduling forms to deal with events, assuming you, as a
developer, have a system already designed.

This started out from a request by a user (Rick) in the 
dBASE newsgroups, who was looking for something he could 
use to plug into his own scheduling software, because he 
wasn't ready to try to create the actual main calendar form. 

He threw out the question, and Romain Strieff jumped in and
created a form that gave the basic layout. Claude Bell grabbed
that and set it so that the first day of the month was in the
correct column. 

From there, I took it and modified it to do more. The main form
is set up to display the currently selected date, to show holidays
(different color), to go to a weekly view, and ultimately to
read events from an event table, displaying them, and allowing the
user to select an event, and bring it up in a form to modify it,
add an event, etc.

Many thanks to Michael Nuwer for putting up with me throwing questions
about design, problems I ran into, and so on at him. He's a great
sounding board ... 

Ivar Jessen, despite making me a bit crazy in all this, has proven
invaluable in helping with the international issues with dates.
That's a hard thing for most Americans to deal with, and he's 
been very helpful on this front. Any messages in the newsgroups that
sound like I'm angry at him ... well ... frustrated perhaps, but not
angry. Most of the frustration comes from finding that just when
I thought I was being clever my fixes were completely wrong ...

Marc van der Bergen came to our rescue with API calls (and windows data
structure) for the LongDateFormat from Windows, which are now in 
DateEx.cc in the method "IntlLongFormat". 

Sound complex? From a *development* point of view, it's taken more
of my time than I expected. From an end-user point of view, well,
I tried to design this to be as useful as possible.

See below for instructions, or read the comments at the top of
the various forms for instructions on what to modify for non-English
languages, and so on.


----------------
How Do I Use It?
----------------
To use this in your own application, you have two options. The simple
one is the first described. The more complex one is just as it sounds,
and will require you study the code in the main form.

   Simple Version
   --------------
   *** WARNING: If you ran an earlier version and are running this
   in a new folder, you may want to delete the BDE Alias that is
   created when it starts

   Copy the files noted below to a special folder, so you can test this
   with the minimum stuff.
    
        kmScheduler.wfm
        kmSchedEvent.wfm
        km24Time.wfm
        kmSmallCal.wfm
        kmSchedColor.wfm
        kenCal4.cc
        Calendar.bmp
        Clock.bmp
        kmScheduler_English.h
           // You could use one of the other language header
           // files, see notes below on Internationalization

   Next, be sure that the dUFLP source code alias is set up, and
   that you have the most recent version of the dUFLP (freeware
   library of code) available to you. This includes the files contained
   in the .zip you got this from (or if you are using this from the
   dUFLP itself, it should be there), dateex.cc and kmCal3.cc. 
   Copy the versions here to the dUFLP folder ... that will ensure you 
   have the most recent version. This code will not work without 
   the dBASE Users' Function Library, as it relies heavily on code 
   there. (The notes about copying/moving those files will be removed
   once this is completed.)

   You may need to copy from the dUFLP folder, the file:
       custButtEnglish.h 
   to the folder you unzipped the Scheduler software into. 
   (Also you can use another language file, if you have this
   already set up, there you go ...)

   Run kmScheduler.wfm.

   *** NOTE: This will create a BDE Alias named "kmScheduler" and it
   will point to the current folder you are running this application
   from. If you examine the code (canOpen event), you can change the 
   location pointed to by the Alias - you should do that before running 
   the form, and note that if the folder pointed to doesn't exist, you 
   will probably run into unexpected (and possibly untrapped) errors.

   *** In addition to the BDE Alias, this will create a table called
   "kmSchedule.dbf" which will include "kmSchedule.mdx" and "kmSchedule.dbt".

   *** Finally, this creates a .ini file named "kmScheduler.ini", which
   contains information used by the forms for the handling of the
   color options for the days in the calendar displays. The form
   kmSchedColor.wfm can be used to modify these colors.

   When this starts, there will be nothing in any of the calendar
   'schedule' or 'agenda' entries.

   Try moving around, click the day button for each day of the month (or
   click in the 'cell' area for the day).

   Try changing months, years, etc. Try the "Today" button.

   Try the "WeekView" button. 

   Now for the fun part, double-click on a day of the week in one of
   the views. This should bring up a form that allows you to add, edit
   or delete entries in the schedule table. There are lots of options,
   most or all of which should be pretty self-explanatory. Repeating
   events are useful, and you have lots of options. 

   Add some events ... 

   Close the events form.

   The events should be displayed in the main calendar form. 

   Try double-clicking on an individual item, and the events form
   should display with the currently selected item showing.

   If you want to compile this into an application, please read
   the details in the comments at the beginning of ALL OF the forms
   ('header' comments), by opening them in the source editor.
   The comments list dependencies -- these are files needed
   to be compiled and deployed with your application. 


   Complex Version
   ---------------
   The complex version of all this assumes that you wish to 
   use this with your own application, which already has 
   a schedule table (or tables), and perhaps a front-end
   to talk to those table(s). (More detail below as
   well as in the comments of the code.)

   Please see details in the file kmScheduler.wfm, in both
   the header comments and in other places. Specific code
   that I am aware of that requires changing to work with
   your application is:
        canOpen
        CheckSchedule
        EventClicked

   That should be it. If it becomes necessary to change 
   anything else, please let me know, so that this can
   be documented for the use of others.


==================
What the files are
==================
All of these files need to be in the same folder as the main form. This
is not set up to use a source alias.

kmScheduler.wfm -- This is the main form, and is what all the rest of this
                   is designed to 'serve'. This form displays a calendar
                   of events, by default a month's view (the current
                   month). It can be changed to a week's view, and you can
                   change the currently selected date by clicking on the
                   'cell' or the date itself.

                   Double-clicking on the center of an empty cell or 
                   in an empty area at the bottom of a cell will
                   bring up a form ("kmSchedEvent.wfm" -- see below)
                   to add a new event for the current date. You can
                   also see all events for that date. 

                   "Events" are whatever you need them to be. They can
                   be annual events, such as a Wedding Anniversary or
                   birthday, regular meetings (say, once a week at
                   a specific time), or whatever you need. Repeating
                   events can be handled easily with this. They are
                   displayed in the main form ...

                   The customization that allows you to use your own
                   form for handling events, and your own tables is in
                   this form. If all you need is this, see the information
                   on customization in the documentation in the form itself.

                   There's a lot more that can be done, including
                   specifying location of the table, and so on ...
                   NOTE: If you change the Alias name and the Table name
                   (see code in the canOpen event), and you want to
                   use kmSchedEvent.wfm (see below) you will have to manually
                   change the names of the alias and table in the database
                   and query objects on the form. 

kmSchedEvent.wfm -- This is the form used to add/modify/delete events
                   in your calendar. It should be pretty straightforward,
                   but just to add some detail: the colors of the 
                   controls displayed are control in the file :dUFLP:FormCntl.cc.
                   If you don't like the colors, you can change them there.

kmSchedColor.wfm -- This form is used to allow the end-user to change the
                   colors of the buttons on the form used to display dates.
                   This modifies the default values stored in kmScheduler.ini.

km24Time.wfm    -- This form is used to interface with the start and end
                   time entryfields, allowing the user to select time between
                   0 and 23 hours, and 00 and 55 minutes (increment of 5 
                   minutes). The user can enter the values themselves in the
                   form, but this is just a nice little UI ...

kmSmallCal.wfm  -- When selecting start/end dates for events, it is useful
                   sometimes to see a calendar. This is just a small calendar
                   form, as opposed to the "big" one used for the main scheduler
                   part of the software. 

kenCal4.cc      -- A copy of :dUFLP:kenCal3.cc with the LoadHolidays method
                   ripped out and replaced by code that gets the holidays
                   array from the LoadHolidays method in kmScheduler.wfm.
                   Please do NOT use kenCal4.cc anywhere except with kmSmallCal.wfm
                   and with this whole set of files. If you try to use it
                   elsewhere, you WILL have problems, I can pretty much guarantee
                   it. Instead, use :dUFLP:kenCal3.cc ...

kmScheduler_languagename.h
                -- These are the 'header' files used to set up the languages.
                   Even if you are using this in English, you need the 
                   english header file. 

Calendar.bmp    -- Image files used for the pushbuttons that call the forms
Clock.bmp          km24Time.wfm and kmSmallCal.wfm.

The form kmScheduler.wfm when run with no modification will create
a BDE Alias ("kmSchedule") and a table ("kmScheduler.wfm"), as well
as a .ini file ("kmScheduler.ini").

If you want to deploy this with your own application, you will need
to compile and deploy the following from the dUFLP (if you include
them in a project this will be handled for you):
   :dUFLP:BDEAlias.cc
   :dUFLP:DateEx.cc
   :dUFLP:Holiday.cc
   :dUFLP:Time.cc
   :dUFLP:Hebrew.cc
   :dUFLP:FormCntl.cc
   :dUFLP:CustButt.cc
   :dUFLP:SetProc.prg
   :dUFLP:Ini.cc
   :dUFLP:StringEx.cc

As you can see, there are a lot of dependencies, but to make something
robust, you have to do that sometimes.


================================================
Internationalization -- Non-English Language Use
================================================
*** I have made all attempts at dealing with international issues that
I can, which includes, with Ivar's help, adding some new methods
to the DateEx.cc class. If you want to use this with a language other 
than English, I am providing any header files that I have (i.e., 
kmScheduler_English.h), and you will want to change the references 
at the top of each .wfm.

*** You should also look for code for changing the language as used
by the DateEx object associated with three of the forms. The changes
are noted in comments in the following forms and the following 
events/methods:
        kmScheduler.wfm   canOpen()
        kmSchedEvent.wfm  init()
        kmSmallCal.wfm    init()

The version(s) released on March 17, 2004 changed this a little,
in that if you call kmSchedEvent.wfm from kmScheduler.wfm, it will
use the language setting from there. If you call kmSmallCal.wfm
from kmSchedEvent.wfm, it will use the language setting from there.
What this means is that if you use this "as is", and change the
dateex class' language property in the main form kmScheduler.wfm
(canOpen event), you don't have to change the property in the
other forms. However, this will not change the header file,
and you will still need to change that to the appropriate 
language ...

*** After changing a header file, you should recompile the individual
form(s), otherwise you may actually see the code running without
the change. 

I had thought that I was overriding the code in :dUFLP:kenCal3.cc
in the startup code for kmSmallCal.wfm to use the correct holiday
names and such, but I wasn't. I had to copy kenCal3.cc to kenCal4.cc
and completely overhaul (strip out and replace) the code for LoadHolidays,
to use the holidays that are defined in kmScheduler.wfm. However,
what this means is that you only have to set up the holidays in one
file, rather than two. This version relies on the code in kmScheduler.wfm
to get the correct names of holidays, and if you change some of them
(remove some, add your own, etc.) it will use that information, rather
than getting it from somewhere else.

*** Finally, in your copy of :dUFLP:CustButt.cc, make sure you set the
appropriate header file there (custButt_languagename.h). 

You may want to copy the different language specific header file(s) 
to the same folder as the forms, or you you may want to use the 
Include folder that is installed with dBASE (on an English computer, 
by default the path is:
    C:\Program Files\dBASE\PLUS\Include  )
If you do that, just copy the header files there and dBASE will
find them when you go to compile the application. Note that it is
not necessary to deploy the .h files with any application
using these forms. Once the forms have been compiled, the contents
of the .h files are included inside them (that's what the #INCLUDE
statement does).

*****
Credit Where Credit Is Due -- The folk who translated the English
Language strings in the kmScheduler_language.h files:
    ( English  -- Ken Mayer )
    Dutch      -- Geert Geerits
    French     -- Marc Hamelin
    German     -- Roland Wingerter
    Italian    -- Franco Asioli
    Portuguese -- Lis Macedo
Other language files will gladly be included in future releases 
of this. Just email them to the administrator of the dUFLP and
they will be added to this .zip file.



=================================================================
SPECIAL NOTE -- MOVING THE CODE TO A NEW FOLDER AFTER RUNNING IT:
=================================================================
If you move this code to somewhere else on the same computer, and you 
want to start over (for example, you tested it, now you want to
use it ...), you will need to delete the BDE Alias in 
the BDE Administrator. When the main form is run again, it will
recreate the alias. If you want to keep the table, just copy the
table (make sure you get the .MDX and .DBT as well as the .DBF).



=============================================
COPYRIGHT, DISCLAIMERS AND PERMISSION FOR USE
=============================================
The code in kmScheduler.wfm, kmSchedEvent, km24Time, kmSmallCal.wfm,
and kmSchedColor.wfm are all copyright (c) 2004 by Ken Mayer. 

While Ken Mayer is an employee of dBASE, Inc., this code is not
an official product of dBASE, Inc., and is not guaranteed by
that company. 

The code in this set of files presented "as is" with no claim to it
being bug-free, and the author is not responsible for problems
in your data that might be incurred by using this code (you should
test with a backup copy of your own data, before implementing this
in any real-world applications).

The above being said, I grant permission to use these, and to modify 
the code if needed (but let me know if you have to do something 
major, it will be useful for other developers). You can also use this
code to learn about some of the things that can be done in dBL
(the dBASE Language). Much of what is done here is not "standard"
coding. It was an educational process for me, which is part of
why I did it in the first place.

-- Ken Mayer, dBASE, Inc. --

////////////////////////////////////////////////////////////
////////////////////// End of File  ////////////////////////
////////////////////////////////////////////////////////////
