OS/2 Shareware BBS: InfoMgt/InfoMgt.zip/excal.zip/EXCAL.INF

OS/2 Help File | 1994-07-11 | 110KB | 718 lines

ΓòÉΓòÉΓòÉ 1. Calendar (ExCal) ΓòÉΓòÉΓòÉ

The calendar provides a means for a user to keep track of their day-to-day
activities. The calendar allows you to view months at a glance and to schedule
events for one or more days.  The events may be scheduled to occur on a single
day, daily, monthly, weekly, or yearly. To remind you of a given event, you can
set an event alarm.

The ExCal package also includes a simple address book.

Related information:

o Getting started
o Example use of calendar and events
o Calendar views
o Calendar events
o Calendar and CUA user interfaces


ΓòÉΓòÉΓòÉ 1.1. Calendar and CUA User Interfaces ΓòÉΓòÉΓòÉ

The Calendar is an example which demonstrates some of the key features of
Workplace interface and the value of using IBM's Common User Access (CUA)
methodology for user interface design and behavior.


ΓòÉΓòÉΓòÉ 1.2. Getting Started ΓòÉΓòÉΓòÉ

When you first install the calendar, a folder is created which contains a
calendar, a folder of event templates, a folder of default places, and an
address book.

When opened, the calendar displays one or more events. When you double-click on
the calendar, it is displays in its default view, the Glance view.

The Event Templates folder contains a set of template events (Lunch, Meeting,
Vacation, etc.). You can add additional event templates if needed. You can
create new events from these templates by dragging one to the calendar.  You
can also create new events by selecting one of the the event template names
listed in the Create event menu choice of a calendar or event.

The Places folder contains a set of default places which can be used when
scheduling where events occur.  You can add additional places if needed.

The Address Book help you keep track of your friends.  To create a new person
for the address book, select Create person from the address book pop-up menu.

To get started, double click the calendar. This will open the calendar in its
default glance view.  You can then add events.


ΓòÉΓòÉΓòÉ 1.3. Example use of Calendar and Events ΓòÉΓòÉΓòÉ

Joseph is working at his desk when he receives a phone call from an important
client. This client would like to meet with Joseph on a particular day to
review his latest sales proposal. Joseph decides to consult his online calendar
to determine if the meeting will be possible. Joseph will need to glance at his
calendar and see what, if anything, is already scheduled for that day. Joseph
double clicks the calendar icon on his screen to open his calendar.

Upon double clicking Joseph is presented with a window showing the calendar in
its default glance view. The leftmost pane shows the current month in a
grid-like fashion similar to what a user would expect to see in a traditional
calendar. Each day of the month is shown in a cell of the grid. Just as Joseph
may write in events for a given day of the month on a traditional calendar,
Joseph may choose one or more of the days in the glance view to show or change
the events for.

Joseph double clicks on the proposed day to determine what events he has
already scheduled for that day.

The events for each day are displayed in the rightmost pane of the glance view.

Upon viewing the events Joseph sees that he has two morning events for that day
and none in the afternoon. He would like to schedule the meeting for two in the
afternoon. He confirms this time with his client and schedules a meeting in his
office. He does this by moving the cursor to the proposed day and bringing up
the pop-up menu for this day.

He then chooses "Create event" which creates the event for this day. The event
is created with a default time and place, which he modifies as described below.


Changing event time

Joseph is still working at his desk an hour later when his important client
calls back. The client informs Joseph that due to a conflict he would like to
make their meeting two hours later. Since Joseph has already scheduled the
meeting in his calendar, he must now change the time of the scheduled event.

Joseph goes to his computer and opens his calendar in the glance view. He opens
on the proposed day to see the events for this day.

Joseph moves the cursor over the meeting event and brings up its pop-up menu.
From this pop-up he chooses "Start time".

A cascaded menu then appears with times in half hour increments. He selects 4pm
and the start time is changed for his event. He repeats these steps in order to
set "End time" for the event.

Joseph is curious and decides he would like to explore a different way to
change his event's time. He opens his event which displays the settings view
for his event. The settings notebook has size pages (i.e. Summary, Time, Place,
Attachments, Window, and General). He selects the time page.

From this page he sees two spin boxes which display the event's "Start time"
and "End time". He then changes the event's time with these.

Having accomplished that task, Joseph becomes more curious and wants to explore
the use of direct manipulation to change the place of his event. Joseph will
need an overhead projector to show his clients some business information.  He
will therefore need to move his customer meeting to a classroom which has this
equipment. He clicks on another day of the month and notices that there is an
event which has the same place he would like to have for his customer meeting.
He opens the setting for the event and notices that it has a "well" with a
place icon in it.

Joseph starts dragging the place over his event and drops it. The place is
updated to reflect the same place as the other event had. The time of day could
be changed in a similar fashion using the time "well" in the event. The time
and place well also have a pop-up menu that can be used to change the place or
time of the event.


Associating objects with an event

Joseph is reviewing his materials for his scheduled meeting with his important
client. He remembers that he has some items (i.e. legal documents and signature
forms) which he must remember to bring to the meeting. He would like to attach
the list of these items to his scheduled event in the calendar so that he does
not forget them.

Joseph goes to his screen to find the necessary documents and forms. He drags
the items over to his event and drops them. They are then added to his event's
list of attachments. He wants to make sure that he has everything, so he opens
his event to double check.

Upon viewing the attachments, he sees that he is missing a signature form. He
finds the form and drags it over to the attachments list in his open event.
Joseph could add the forms to the "Attachments Open on Alarm" list (not shown
above) instead of the "Attachments List" on the same page if he wanted them to
be opened at the time the event alarm occurred just as if he had double-clicked
them.

After finishing all this, Joseph gets another call from his client saying that
he would like to change the day of their meeting. He would like to move it
forward a couple of days. Joseph opens his calendar in the glance view and
finds the meeting event on the previously scheduled day. He drags the event
over the new proposed day and drops it. The event is then updated to occur on
the new day.


Calendar and event presentation cues to purpose

While preparing for his meeting, Joseph glances at his calendar and notices
that the day before his meeting is a weekend. This weekend will affect his
ability to obtain the proper financial documents from his bank. Realizing this
fact, he changes his plans for the Friday before the weekend in order to get
the documents before his meeting.

Joseph was able to determine this quickly because the weekends are
distinguished from the weekdays using different shadings. He then plans to have
the documents completed the prior Friday for his Monday meeting.

While sitting at his desk, Joseph receives a call from a friend wanting to make
dinner plans for that evening. Joseph again consults his calendar and easily
finds the current day as it has a different shading then the other days.

He views his events for this day and sees that he is free for dinner. Joseph
then brings up the pop-up menu for this day to create a new event. He is
reassured that he is adding the event to the correct day because the day has
context emphasis (i.e. dashed box).

After finishing the phone call with his friend, Joseph's manager informs him
that there is a mandatory two day seminar which he must attend. Joseph opens
his calendar and selects the two days. The two days are hilighted indicating
that they have been selected. He then brings up a pop-up menu for the two days
and schedules and creates a seminar event for them.

Later that day, Joseph sits back and looks at his calendar. He realizes that
this is going to be a busy month. He notices that he has something scheduled
for most days because the number for each day is underlined indicating that he
has event(s) scheduled for those days.

The calendar provides visual feedback to tell the user what action is taking
place or what object is being acted on. Additionally the calendar combines
different colors and emphasis to indicate to the user unique things about
certain days. (i.e. diagonal lines).


ΓòÉΓòÉΓòÉ 1.4. Calendar Events ΓòÉΓòÉΓòÉ

Related information:

o Viewing calendar events
o Setting event alarms
o Adding and removing event attachments
o Changing event time or date


ΓòÉΓòÉΓòÉ 1.5. Calendar Views ΓòÉΓòÉΓòÉ

The calendar supports three views of its events: Glance, Icon, and Details
view.

o Calendar Glance view
o Calendar Icon view
o Calendar Details view

The font and color of each of these can be set using the Font, Color, or Scheme
Palette in your System Setup folder.


ΓòÉΓòÉΓòÉ 1.6. Calendar Glance View ΓòÉΓòÉΓòÉ

The calendar's default view is Glance view. This is similar to the "month at a
glance" presentation found in most traditional calendars.

The leftmost pane, glance, shows the current month in a grid-like fashion. From
here you have various menu choices depending upon whether the pop-up menu is
initiated on the day or the entire pane. If you bring up a pop-up menu from the
day

the menu choices are as follows

o View events
o Delete events
o Create events

If you bring up a pop-up menu for the left pane,

the menu choices are as follows

o Next month
o Previous month
o Month
o Other month
o Refresh now
o Sort events

The rightmost pane, events, shows all the events which occur on a given day or
days. If you bring up a pop-up menu over an event the following menu for the
event will appear.

The pop-up menu includes

o Start time
o Duration in hours
o End time
o Day
o Repeat
o Replace place with
o Turn alarm on

If you bring up the pop-up menu for the rightmost pane

the pop-up menu includes

o Create event
o Delete past events


ΓòÉΓòÉΓòÉ 1.7. Calendar Icon View ΓòÉΓòÉΓòÉ

The icon view of the calendar displays all the events in the calendar with no
filtering based on days or months as provided by the glance view.


ΓòÉΓòÉΓòÉ 1.8. Calendar Details View ΓòÉΓòÉΓòÉ

The details view of the calendar displays all the events in the calendar in a
report-like format. Each event is listed with its summary information (i.e.
date, time, and place).


ΓòÉΓòÉΓòÉ 1.9. Viewing Calendar Events ΓòÉΓòÉΓòÉ

You can view the events for a single or multiple days from  the calendar.
There are several methods provided for viewing the events, depending upon your
preference.

Glance day pop-up menu

This is done by selecting mouse button 2 while the cursor is over the day to
viewed. If you would like to see the events occurring for more than one day,
select the days and then select the "View Events" choice.

This will cause the appropriate events to be displayed in the right pane of the
calendar window. Any events previously in view will remain in view.

Double click on glance day

You can double-click the mouse over the day and only the events for that day
will be displayed in the right pane of the calendar.

Calendar menu "Selected" choice

This method is similar to the pop-up menu method except that you select "View
Events" from the "Selected" menu pulldown.

The calendar events are displayed on the right pane of the calendar window as
shown below.


ΓòÉΓòÉΓòÉ 1.10. View Events ΓòÉΓòÉΓòÉ

This option displays all the events occurring on the specified day(s). If the
pop-up menu is for a day which is not selected, only the events for that day
are displayed. If the pop-up menu is for a day which is selected, the events
occurring on that day and any other selected days are displayed. For additional
information on viewing calendar events, refer to Viewing Calendar Events


ΓòÉΓòÉΓòÉ 1.11. Create Events ΓòÉΓòÉΓòÉ

This option creates an event(s) for the specified day(s). If the pop-up menu is
for a day which is not selected, an event is created for that day only. If the
pop-up menu is for a day which is selected, a separate event is created for
that day and each selected day. If the pop-up menu is on the events pane, an
event is created for the first day in view (or, if no days are in view, an
event is create for today).


ΓòÉΓòÉΓòÉ 1.12. Delete Events ΓòÉΓòÉΓòÉ

This option deletes all events occurring on the specified day(s). If the pop-up
menu is for a day which is not selected, only the events for that day are
deleted. If the pop-up menu is for a day which is selected, the events
occurring on that day and any other selected days are deleted.


ΓòÉΓòÉΓòÉ 1.13. Next Month ΓòÉΓòÉΓòÉ

This displays the next month of the calendar.


ΓòÉΓòÉΓòÉ 1.14. Previous Month ΓòÉΓòÉΓòÉ

This displays the previous month of the calendar.


ΓòÉΓòÉΓòÉ 1.15. Month ΓòÉΓòÉΓòÉ

You can use this option to quickly change the glance view month to a month
which occurs within seven months of the current month.


ΓòÉΓòÉΓòÉ 1.16. Other Month ΓòÉΓòÉΓòÉ

This option brings up a dialog allowing you to select which month is displayed
by the calendar.


ΓòÉΓòÉΓòÉ 1.17. Refresh Now ΓòÉΓòÉΓòÉ

This option refreshes both panes of the glance view.


ΓòÉΓòÉΓòÉ 1.18. Sort Events ΓòÉΓòÉΓòÉ

Choose this option to sort the events by name or time.


ΓòÉΓòÉΓòÉ 1.19. Import/Export from PMDiary ΓòÉΓòÉΓòÉ

Choose this option to import from or export to a PMDiary daily planner file
(*.$D$). The Calendar will try to match events it is importing from PMDiary by
title and time.  When exporting Calendar will merge the events it contains with
the PMDiary entries in the export file.


ΓòÉΓòÉΓòÉ 1.20. Delete Past Events ΓòÉΓòÉΓòÉ

This choice presents a list of events which occurred before the current date.
Pick from the list of events those you no longer want and select Delete.


ΓòÉΓòÉΓòÉ 1.21. Programming API ΓòÉΓòÉΓòÉ

The Calendar supports Workplace Shell setup strings.  These strings can be
passed to a Calendar to create events with the SysSetObjectData or
WinSetObjectData API.  The Calendar will create an event and pass it the setup
string. Generally this is done as part of a customized Calendar installation.

Note:  You can create events directly using the SysCreateObject or
WinCreateObject API and specifying the event class ExEvent.  In this case, the
CREATEEVENT keyword is not necessary (i.e., the CREATEEVENT keyword is only
used by Calendar instances). See EXCAL.CMD included in this package for more
details.

CREATEEVENT=        New event title.

DATE=               Date for the new event, MM/DD/YY.  Defaults to current
                    date.

STARTTIME=          Start of event, HH:MM, in 24 hour format.  Defaults to noon
                    or current hour, whichever is later.

ENDTIME=            End of event, HH:MM, in 24 hour format.  Defaults to 13:00
                    or current hour plus one hour, whichever is later.

REPEAT=             Valid values are NONE, WEEKLY, MONTHLY, or ANNUALLY.

ALARM=              Valid values are ON or OFF.

PERSONAL=           Valid values are YES or NO.  If YES, the event will not be
                    included in exports to PMDiary.

PLACE=              The title of an existing place.

NOTES=              Notes for the event.

ATTACHMENTWPOBJECTHANDLES= The list of object handles attached to the event,
                    separated by spaces. The attachments must exist in the same
                    folder (calendar) as the event.

ATTACHMENTWPOBJECTIDS= Same as ATTACHMENTWPOBJECTHANDLES except it accepts
                    object IDs (e.g., <WP_TEMPS> for the Templates folder, see
                    \OS2\INI.RC for the standard system object IDs).

ALARMATTACHMENTWPOBJECTHANDLES= The list of object handle attached to the
                    event, separated by spaces, which will be opened when the
                    event alarm occurs. The attachments must exist in the same
                    folder (calendar) as the event.

ALARMATTACHMENTWPOBJECTIDS= Same as ALARMATTACHMENTWPOBJECTHANDLES except it
                    accepts object IDs (e.g., <WP_OS2SYS> for the OS/2 System
                    folder, see \OS2\INI.RC for the standard system object
                    IDs).

OPENONALARM=        Valid values are YES or NO.  If YES, the event will be
                    opened when the event alarm occurs.

BEEPONALARM=        Valid values are YES or NO.  If YES, the event will beep
                    when the event alarm occurs.

EXPORTTOPMDIARY=    Specifies a PMDiary file to export calendar events. The
                    file name must be fully qualified.  The events starting
                    from the current time to two years into the future are
                    exported.  During exporting, existing PMDiary events are
                    merged with the ExCal events.

IMPORTFROMPMDIARY=  Specifies a PMDiary file to import calendar events. The
                    file name must be fully qualified.

The setup string below would create an annual event.

 CREATEEVENT=Happy New Years!;
 DATE=01/01/93;
 REPEAT=ANNUALLY;
 STARTTIME=00:01;
 ALARM=ON

This setup string can be passed to the Calendar using the WinSetObjectData API,
the REXX SysSetObjectData, or the Workplace Shell wpSetup method.  The Calendar
creates an Event and passes it the entire setup string passed to the Calendar
including the CREATEEVENT keyword (which is ignored by the newly created
event).

Note:  Only one event can be created per setup invocation because the
CREATEEVENT keyword can only be specified once in the setup string.

Similarly, places can be created by the Calendar.

Note:  You can create places directly using the SysCreateObject or
WinCreateObject API and specifying the place class ExPlace.  In this case, the
CREATEPLACE keyword is not necessary (i.e., the CREATEPLACE and PLACEFOLDER
keywords are only used by Calendar instances). Only one place can be created
per setup invocation because the CREATEPLACE keyword can only be specified once
in the setup string.

CREATEPLACE=        New place title.

PLACEFOLDER=        Object ID or fully qualified path of folder where new place
                    is to be created.  Default is <EXCAL_PLACESFOLDER>.

ADDRESS=            Address.

PHONE=              Phone number.

CITY=               City.

STATE=              State.

ZIPCODE=            Zip code.

CONTACTNAME=        Contact name.

CONTACTPHONE=       Contact phone number.

CAPACITY=           Number of people the place can confortably hold.

NOTES=              Notes about the place.

The Calendar, Event, and Place objects also support the following keywords.

QUERYSETUPSTRINGSLENGTH= Returns the length of the setup strings necessary to
                    recreate the ExCal object into into a named shared memory
                    object.

QUERYSETUPSTRINGS=  Returns the setup strings necessary to recreate the ExCal
                    object into into a named shared memory object.

WRITESETUPSTRINGSTOFILE= Requests that the event, place, or calendar write the
                    setup strings necessary to recreate it to the named file.
                    The file name must be fully qualified.  If multiple setup
                    strings are required, they are separated by a NULL
                    character and the data is terminated by a double-NULL
                    character (a "pszz"). Note the Calendar object writes out
                    the setup strings necessary to recreate it, the Place
                    objects, and the Event objects it contains.


ΓòÉΓòÉΓòÉ 2. Events (ExCal) ΓòÉΓòÉΓòÉ

An event provides a means for a user to keep track of their day-to-day
activities. An event may be scheduled to occur on a single day, daily, monthly,
weekly, or yearly. To remind you of a given event, you can set an event alarm.

Related information:

o Getting started
o Example use of events
o Changing event time or date
o Setting event alarms
o Adding and removing event attachments
o Calendar and CUA user interfaces


ΓòÉΓòÉΓòÉ 2.1. Setting Event Alarms ΓòÉΓòÉΓòÉ

You can set an alarm for each event in the calendar. There are various ways
that can be used to set the alarms, depending upon your preference.

Event pop-up menu

Display the event's pop-up menu by selecting mouse button 2 while the cursor is
over the event whose alarm is to be set. If more there is more than one event
whose alarm is being set, extended selection may be used to choose the events.
The pop-up menu should then be brought up and the "Turn alarm on" or "Turn
alarm off"  choice selected.

This menu item is toggled between "on" and "off" depending upon  whether the
event has an alarm set or not. The default is for the alarm to occur five
minutes prior to the start time of the event.

Open Event Settings

Open the event's Settings by double-clicking mouse button 1 while the cursor is
over the event whose alarm is to be set. Once open, the events setting's
Summary page is displayed. From here you can toggle the alarm on or off.
Additionally, you can change the time the alarm is to go off, relative to the
start of the event.

Calendar menu "Selected" choice

This method is similar to the pop-up menu method except that you select "Turn
alarm on" from the "Selected" menu pulldown.


ΓòÉΓòÉΓòÉ 2.2. Changing Event Time or Date ΓòÉΓòÉΓòÉ

There are various ways to change an events time and/or date.

Event pop-up menu

Move the cursor over the event and bring up its pop-up menu. The pop-up menu
includes

o Start time
o Duration in hours
o End time
o Day
o Repeat

Event Settings

Open the event settings and turn to the Time page.

The Time page contains spin boxes which can be used to change the date (month,
day, and year) and the start and end time.

Direct Manipulation

Each event contains a time "well" which will always contain only one time
object.

Using direct manipulation, you can drag any time object to the time "well" and
it replace the one currently there. The time well also has a pop-up menu that
can be used to change the time of the event.


ΓòÉΓòÉΓòÉ 2.3. Start time ΓòÉΓòÉΓòÉ

Use this choice to set the starting time of an event.

Once set the ending time is adjusted based on the duration of the event. If
additional granularity is need for time (e.g. 8:15), open the Settings for the
event and turn to the Time page.


ΓòÉΓòÉΓòÉ 2.4. Duration ΓòÉΓòÉΓòÉ

Use this choice to set the duration of an event.

Upon changing the duration of an event, the starting time for the event remains
the same, and the ending time is adjusted to account for the change in
duration. If a longer duration is needed (e.g. 6 hours), open the Settings for
the event and turn to the Time page.


ΓòÉΓòÉΓòÉ 2.5. End time ΓòÉΓòÉΓòÉ

Use this choice to set the ending time of an event.

Upon changing the ending time of an event, the duration of the event is changed
to account for the change in the ending time. There is no changes made to the
starting time. If additional granularity is need for time (e.g. 8:15), open the
Settings for the event and turn to the Time page.


ΓòÉΓòÉΓòÉ 2.6. Day ΓòÉΓòÉΓòÉ

Use this choice to set the day of the event.  The cascaded menu choices are the
current day (today) and the next six days.  If the event day you want to set is
more than six days from today, open the event Settings and turn to the Time
page to set the event date.


ΓòÉΓòÉΓòÉ 2.7. Repeat ΓòÉΓòÉΓòÉ

Choose one of these choices to have an event repeat for a given number of days,
weeks, months, or years.

You can limit the number of occurrences of a repeating events by selecting one
of the menu cascade choices (e.g. "For two days"), or by opening the event
Settings and turning to the Time page to set the number of occurrences.


ΓòÉΓòÉΓòÉ 2.8. Replace place with ΓòÉΓòÉΓòÉ

Choose one of these choices to change the location where an event is to occur.
Not all of the available places are shown in this menu: Open the event Settings
and turn to the Places page to see all available locations.

Note:  You may create more places by selecting Create another from an existing
place. Also, you can set the place of an event by dropping a place on the
event.


ΓòÉΓòÉΓòÉ 2.9. Turn alarm on ΓòÉΓòÉΓòÉ

This toggles the event alarm on or off. If the alarm is being turned on, it is
set to occur five minutes prior to the event start time. This may be changed by
opening the settings of the event and changing the alarm advance minutes from
the Summary page.


ΓòÉΓòÉΓòÉ 2.10. Personal ΓòÉΓòÉΓòÉ

This toggles the personal attribute of an event.  Personal events are excluded
from exports to PMDiary.


ΓòÉΓòÉΓòÉ 2.11. Adding and Removing Event Attachments ΓòÉΓòÉΓòÉ

Attachments may be associate with an event as a reminder of things you might
need when the event occurs. For example, you may have a business meeting to
which you would like to bring presentation material.  You can associate any
workplace object with an event, such as a document, video presentation, or
program. Each event can have any number of attachments associated with it. To
do this, open the event settings and turn to the "Attachments" page.

Using direct manipulation techniques, drag the object you would like to
associate to the the attachment area of the event setting's page.

Attachments added to the "Attachments Opened On Alarm" are opened when the
event alarm occurs.  This can be used to open a document or start a program
when the event occurs.

Attachments can be removed by either deleting the attachment, or moving the
attachment to another folder.

Note:  Event attachments can only be shadows (references to) other objects such
as documents and forms, or program references.  The attachments are deleted
when the event is deleted.


ΓòÉΓòÉΓòÉ 3. Places (ExCal) ΓòÉΓòÉΓòÉ

Places are used in conjuction with events. An event provides a means for a user
to keep track of their day-to-day activities. An event may be scheduled to
occur on a single day, daily, monthly, weekly, or yearly. To remind you of a
given event, you can set an event alarm.

Related information:

o Getting started
o Example use of events and places


ΓòÉΓòÉΓòÉ 3.1. Make default ΓòÉΓòÉΓòÉ

Use this choice to set the default place used by newly created events.  When
the Calendar is initially installed, the place named Favorite Place is the
default place for newly created events.


ΓòÉΓòÉΓòÉ 4. Address Book and Persons (ExCal) ΓòÉΓòÉΓòÉ

The address book provides a means for a user to keep track of their friends.
To create a new person for the address book, select Create person from the
address book pop-up menu.

Note:  You can hide an unneeded column of detail information shown for each
person by deselecting the column name in the Details to display list shown in
the third View page of the Address Book's Settings view.