(****
 *
 * Module View defines the objects and operations related to the different
 * calendar views available to the user.  The structural viewing levels are
 * item, day week, month, and year.  There are operations to go to the previous
 * and next views at any level, as well as an operation to go to a specific
 * date.  Lists of scheduled items can be viewed in a variety of ways.  A
 * general view filter operation can be applied to both structural and list
 * views.  Operations are available to view other users' calendars and to view
 * a list of active viewing windows.
 *
 * NOTE: this is work in progress.  A good deal of objects are yet to be
 * defined.
 *
 *)
module View;

  import CalendarDB.CalendarDB;
  import Schedule.ScheduledItem, Schedule.StartTime, Schedule.Duration,
         Schedule.Title, Schedule.Category, Schedule.Date, Schedule.Hours,
         Schedule.Minutes, Schedule.DateNumber;

  object DailyAgenda
    components: FullDayName and EventTitle* and TimeSlotDescriptor* and
        TaskDescriptor*;
    description: (*
        A DailyAgenda is contains scheduled item information for a calendar
        day.  The FullDayName consists of the day name itself (e.g.,
        Wednesday), the month, the numeric date, and the year.  The EventTitle
        list contains the titles of zero or more events scheduled to occur on
        this day.  The TimeSlotDescriptor list contains time-tagged descriptors
        for scheduled appointments and meetings.  The TaskDescriptor list is an
        number list of tasks scheduled to be due on this day.
    *);
  end DailyAgenda;

  object FullDayName
    components: DayName and MonthName and DateNumber and Year;
    description: (*
	A FullDayName has the complete and unique designation of a calendar
        day.
    *);
  end FullDayName;

  object DayName = Sunday or Monday or Tuesday or Wednesday or Thursday or
        Friday or Saturday
    description: (* 
        The standard names of the days of the week.
    *);
  end DayName;

  object Sunday
    description: (* One of the seven days of the week. *);
  end;

  object Monday
    description: (* One of the seven days of the week. *);
  end;

  object Tuesday
    description: (* One of the seven days of the week. *);
  end;

  object Wednesday
    description: (* One of the seven days of the week. *);
  end;

  object Thursday
    description: (* One of the seven days of the week. *);
  end;

  object Friday
    description: (* One of the seven days of the week. *);
  end;

  object Saturday
    description: (* One of the seven days of the week. *);
  end;

  object MonthName = January or February or March or April or May or June or
        July or August or September or October or November or December
    description: (*
        One of the twelve months of the year.
    *);
  end MonthName;

  object January
    description: (* One of the twelve months of the year. *);
  end;

  object February
    description: (* One of the twelve months of the year. *);
  end;

  object March
    description: (* One of the twelve months of the year. *);
  end;

  object April
    description: (* One of the twelve months of the year. *);
  end;

  object May
    description: (* One of the twelve months of the year. *);
  end;

  object June
    description: (* One of the twelve months of the year. *);
  end;

  object July
    description: (* One of the twelve months of the year. *);
  end;

  object August
    description: (* One of the twelve months of the year. *);
  end;

  object September
    description: (* One of the twelve months of the year. *);
  end;

  object October
    description: (* One of the twelve months of the year. *);
  end;

  object November
    description: (* One of the twelve months of the year. *);
  end;

  object December
    description: (* One of the twelve months of the year. *);
  end;

  object Year = integer
    description: (*
        The four-digit year number.  (Yes, this Calendar Tool has a Y10K
        problem.)
    *);
  end Year;

  object EventTitle = Title
    description: (*
        The title of an event as shown in the list of events for a day.
    *);
  end;

  object TimeSlotDescriptor
    components: TimeSlotName and BriefItemDescriptor* and Overlaps;
    description: (*
        A time slot descriptor represents one slot (physically, a row) in a
        daily agenda.  The TimeSlotName component is the start time for the
        slot.  The list of BriefItemDescriptors contains the items that begin
        within the slot, where "within" is defined as the start time plus the
        current time increment.  The overlaps component is a list of items with
        start times that overlap with an item in the BriefItemDescriptor list.
    *);
  end TimeSlotDescriptor;

  object TimeSlotName
    components: TimeValue and AmOrPm;
    description: (*
        A TimeSlotName consists of a numeric TimeValue and an AmOrPm indicator.
        TO DO: this definition should be reconciled as appropriate with the
        definition of Time in the Schedule module.
    *);
  end Time; 

  object TimeValue = integer
    description: (*
        The numeric value of a time of day, in a 12-hour or 24-hour clock.
        Which clock type currently in use is determined by a user-selectable
        option setting.
    *);
  end;

  object AmOrPm = AM or PM
    description: (*
        Normal suffix used in 12-hour time value.
    *);
  end AmOrPm;

  object AM
    description: (* The 12-hour time suffix indicating a morning time. *);
  end;

  object PM
    description: (* The 12-hour time suffix indicating an afternoon time. *);
  end;

  object BriefItemDescriptor
    components: Title and StartTime and Duration and Category;
    description: (*
        A brief item descriptor contains a subset of the information for a full
        scheduled item.  The information is a Title, StartTime, Duration, and
        Category.
    *);
  end BriefItemDescriptor;

  object Overlaps
    components: BriefItemDescriptor*;
    description: (*
        Overlaps contain zero or more BriefItemDescriptors that overlap with
        with the master item in a given time slot.  An overlapping item is one
        with a StartTime within the same time slot as other items.  The
        "master" item in a time slot is the item that is first in a sorted
        order based on start time, duration, and alphabetic title as the
        primary, secondary, and tertiary sort keys, respectively.
    *);
  end Overlaps;

  object TaskDescriptor
    components: TaskNumber and TaskTitle;
    description: (*
        A TaskDescriptor is one item in a number list of tasks.
    *);
  end TaskDescriptor;

  object TaskNumber = integer
    description: (*
        The ordinal number of a task relative to other tasks.
    *);
  end;

  object TaskTitle = Title
    description: (*
        The free-form title of a task.
    *);
  end;

  object DailyFormatOptions
    components: NormalTimeRangeOption and TimeIncrementOption and
        IncrementHeightOption and ShowHide24HoursOption and
        ShowHideExactTimeOption and ShowHideDashedLinesOption and
        ShowHideExtensionArrowsOption and ProportionalSpacingOnOffOption and
        DisplayOverlapsOption and ShowHideEventsOption and
        ShowHideTasksOption and DefaultHeightAndWidthOption;
    description: (*
        DailyFormatOptions control the details of how daily agenda information
        is formated.
    *);
  end DailyFormatOptions;

  object NormalTimeRangeOption = StartTime and EndTime
    description: (*
        NormalTimeRangeOption defines the starting and ending times that
        normally appear in the left column of the daily agenda.  The default
        range of times is 8AM to 5PM.
    *);
  end;

  object TimeIncrementOption = Hours and Minutes
    description: (*
        TimeIncrementOption defines the time increment of the left column
        labels in the daily agenda.  The smallest allowable time increment is
        five minutes, the largest is twelve hours.  When the time increment is
        less than one hour, the time labels are shown in hour and minute
        format; when the increment is one hour or greater, the labels are shown
        as hours with no minutes.  The default increment is one hour.
    *);
  end;

  object IncrementHeightOption = integer
    description: (*
        IncrementHeightOption option defines the default minimum number of text
        lines shown in each time increment of a daily agenda.  If there are
        more items starting in an increment than fit in the minimum number of
        lines, the system automatically increases the height for that increment
        to a size sufficient to display all items fully.  The default value is
        two lines per increment.
    *);
  end;

  object ShowHide24HoursOption = Show or Hide
    description: (*
        ShowHide24HoursOption toggles between showing a full 24 hours of
        display versus the normal time range only in daily agenda.  If the
        24-hour time range is shown, non-normal times are shown with a light
        grey background, to distinguish them from normal times.  The default
        value for this option is to hide non-normal times.
    *);
  end;

  object ShowHideExactTimeOption = Show or Hide
    description: (*
        ShowHideExactTimeOption toggles between showing or not showing the
        starting and ending times for each scheduled item immediately to the
        left of the title in a daily agenda.  This option is useful when items
        do not typically start or end exactly on the hour.  The default value
        for this option is to hide the exact time.
    *);
  end;

  object ShowHideDashedLinesOption = Show or Hide
    description: (*
        ShowHideDashedLinesOption toggles between showing and not showing the
        dashed lines that appear above and below items that do not start or end
        on the hour in a daily agenda.  The default is to show dashed lines.
    *);
  end;

  object ShowHideExtensionArrowsOption = Show or Hide
    description: (*
        ShowHideExtensionArrowsOption toggles between showing and not showing
        the down-pointing arrows for items with end times that extend beyond
        the hour of the start time in a daily agenda.  The default is to show
        extension arrows.
    *);
  end;

  object ProportionalSpacingOnOffOption = On or Off
    description: (*
        ProportionalSpacingOnOffOption toggles between placing items
        proportionally down from the top of the hour based on starting time in
        a daily agenda.  When the option is off, the first (only) item in an
        hour is placed at the top of that hour and any other items starting in
        the hour are placed immediately below it.  The default is proportional
        spacing on.
    *);
  end;

  object DisplayOverlapsOption = Horizontal or Vertical
    description: (*
        DisplayOverlapsOption controls how items with overlapping times are
        displayed in a daily agenda.  When displayed horizontally, overlapping
        items appear side-by-side in separate columns of the day view.  When
        displayed vertically, overlapping items appear on separate lines in a
        single column, sorted by start time, duration, and title.  The default
        is horizontal display.
    *);
  end;

  object ShowHideEventsOption = Show or Hide
    description: (*
        ShowHideEventsOption toggles between showing or not showing the list of
        events in a daily agenda.  The default is to show events if any are
        scheduled.
    *);
  end;

  object ShowHideTasksOption = Show or Hide
    description: (*
        ShowHideTasksOption toggles between showing or not showing the list of
        tasks in a daily agenda.  The default is to show tasks if any are
        scheduled.
    *);
  end;

  object DefaultHeightAndWidthOption = Height and Width
    description: (*
        DefaultHeightAndWidthOption controls the width and height of the full
        daily agenda.  If one or both of the default dimensions is too small to
        accommodate all information in the display, the information is
        truncated appropriately and scrollbars are added to the display window.
    *);
  end;

  object EndTime = TimeSlotName
    description: (*
        Ending time in the normal time range option.
    *);
  end;

  object Show
    description: (*
        Option indicator for a show/hide option, indicating that the option
        state is "show".
    *);
  end;

  object Hide
    description: (*
        Option indicator for a show/hide option, indicating that the option
        state is "hide".
    *);
  end;

  object On
    description: (*
        Option indicator for an on/off option, indicating that the option state
        is "on".
    *);
  end;

  object Off
    description: (*
        Option indicator for an on/off option, indicating that the option state
        is "off".
    *);
  end;

  object Horizontal
    description: (*
        Option indicator for displaying overlaps horizontally.
    *);
  end;

  object Vertical
    description: (*
        Option indicator for displaying overlaps vertically.
    *);
  end;

  object Height = integer
    description: (*
        Height value for the default height and width option.
    *);
  end;

  object Width = integer
    description: (*
        Width value for the default height and width option.
    *);
  end;

  op ViewItem(Date, CalendarDB)->ScheduledItem;
  op ViewDay(Date, CalendarDB)->DailyAgenda;

end View;