@database "calendar_gc"
@master "Work:V42/src/workbench/classes/gadgets/calendar/calendar_gc.doc"

@Node Main "calendar_gc.doc"
    @{" --datasheet-- " Link "--datasheet--"}
    @{" GM_DOMAIN " Link "GM_DOMAIN"}
    @{" GM_GOACTIVE " Link "GM_GOACTIVE"}
    @{" GM_GOINACTIVE " Link "GM_GOINACTIVE"}
    @{" GM_HANDLEINPUT " Link "GM_HANDLEINPUT"}
    @{" GM_HITTEST " Link "GM_HITTEST"}
    @{" GM_LAYOUT " Link "GM_LAYOUT"}
    @{" GM_RENDER " Link "GM_RENDER"}
    @{" OM_DISPOSE " Link "OM_DISPOSE"}
    @{" OM_NEW " Link "OM_NEW"}
    @{" OM_SET " Link "OM_SET"}
@EndNode

@Node "--datasheet--" "calendar.gadget/--datasheet--"
 
@{b}     NAME@{ub}
        calendar.gadget--Monthly calendar gadget                (V42)
 
@{b}     SUPERCLASS@{ub}
        gadgetclass
 
@{b}     DESCRIPTION@{ub}
        The calendar gadget class is used to display a month-based array
        of days in the visual style of traditional calendars.
 
@{b}     METHODS@{ub}
        OM_NEW--Create the gadget.  Passed to superclass, then @{"OM_SET" Link "OM_SET"}.
 
        OM_SET--Set object attributes.  Passed to superclass first.
 
        OM_UPDATE--Set object notification attributes.  Passed to superclass
            first.
 
        GM_LAYOUT--Calculate relative gadget coordinates.  Passed to
            superclass first.  Requires V39 or beyond of Intuition.
 
        GM_RENDER--Renders the gadget imagry.  Overrides the superclass.
 
        GM_HITTEST--Determines if mouse is within the gadget rectangle.
            Overrides the superclass.
 
        GM_GOACTIVE--Handles activation, mutual-exclusion and date-select.
            Overrides the superclass.
 
        GM_HANDLEINPUT--Handles input events once active.  Handles cycle
            buttons, repeat and RMB abort.  Overrides the superclass.
 
        GM_GOINACTIVE--Deselects the button.  Overrides the superclass.
 
        GM_DOMAIN--Obtain the minimum size of a calendar object.
 
        All other methods are passed to the superclass, including @{"OM_DISPOSE" Link "OM_DISPOSE"}.
 
@{b}     ATTRIBUTES@{ub}
        GA_Disabled (BOOL) -- Determines whether the calendar is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  A disabled
            calendar's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern that is rendered in SHADOWPEN.
            Defaults to FALSE.
 
        GA_TextAttr (struct @{"TextAttr" Link "TEXT_INCLUDE:graphics/text.h/Main" 63} *) -- Text attribute for the font to
            use for the labels.
 
        GA_ReadOnly (BOOL) -- Indicate whether calendar has selectable days
            or is for display only.  Defaults to FALSE (selectable days).
 
        CALENDAR_ClockData (struct @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22} *) -- Pointer to a @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22}
            structure (defined in @{"<utility/date.h>" Link "TEXT_INCLUDE:utility/date.h/Main" 0}) used to set the current
            date information, including month, day and year.
 
        CALENDAR_Day (LONG) -- Set the current day of the month.
 
        CALENDAR_FirstWeekday (LONG) -- Sets the first day of the week.
            Defaults to 0, which is Sunday.
 
        CALENDAR_Days (STRPTR *) -- Array of localized column labels,
            starting with Sunday as day[0].  English versions are built
            in.
 
        CALENDAR_Labels (LONG) -- Optional array of day description
            records.  This allows individual control over the appearance
            of each day of the month.  Changing this attribute will
            invoke @{"GM_RENDER" Link "GM_RENDER"}.  If provide, the array must contain 31
            entries.
 
        CALENDAR_Label (BOOL) -- Indicate whether there should be a label
            across the top showing the names of the days of the week.
            Defaults to TRUE.
 
@{b}     NOTES@{ub}
        Relative support requires V39 and beyond of Intuition.
 
@EndNode

@Node "GM_DOMAIN" "calendar.gadget/GM_DOMAIN"
 
@{b}     NAME@{ub}
        GM_DOMAIN--Obtain the domain of an object               (V42)
 
@{b}     FUNCTION@{ub}
        The GM_DOMAIN method is used to obtain the domain of a
        calendar.gadget object before ever creating an object.
 
        Requires a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 52} pointer in gpd_RPort with the correct font
        attributes.  Only supports the gpd_Which==GDOMAIN_MINIMUM type.
 
@{b}     ATTRIBUTES@{ub}
        The following attributes can be specified.
 
        CALENDAR_Days (STRPTR *) -- Array of localized column labels,
            starting with Sunday as day[0].
 
        CALENDAR_Label (BOOL) -- Indicate whether there should be a label
            across the top showing the names of the days of the week.
            Defaults to TRUE.
 
@{b}     RESULT@{ub}
        Returns 1 and fills in the gpd_Domain field.
 
@EndNode

@Node "GM_GOACTIVE" "calendar.gadget/GM_GOACTIVE"
 
@{b}     NAME@{ub}
        GM_GOACTIVE--Activate a gadget.                         (V42)
 
@{b}     FUNCTION@{ub}
        The GM_GOACTIVE method is used to indicate to a gadget that it has
        become active.  This method overrides the superclass.
 
@{b}     RESULT@{ub}
        Returns GMR_MEACTIVE.
 
        Sets the *msg->gpi_Termination field to CALENDAR_Day, which in turn
        fills in the IntuiMessage->Code field.
 
@EndNode

@Node "GM_GOINACTIVE" "calendar.gadget/GM_GOINACTIVE"
 
@{b}     NAME@{ub}
        GM_GOINACTIVE--Gadget has lost activation.              (V42)
 
@{b}     FUNCTION@{ub}
        The GM_GOINACTIVE method is used to indicate that the calendar has
        become inactive.  This method overrides the superclass.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "GM_HANDLEINPUT" "calendar.gadget/GM_HANDLEINPUT"
 
@{b}     NAME@{ub}
        GM_HANDLEINPUT--Handle input events.                    (V42)
 
@{b}     FUNCTION@{ub}
        The GM_HANDLEINPUT method is used to handle the input events of an
        active calendar gadget.  This method overrides the superclass.
 
        This method correctly handles RMB abort.
 
        If CALENDAR_Multiselect was specified at creation time, then
        a notification event is sent for each day selected.  The day is
        sent in the CALENDAR_Day attribute.  0x100 is set if the day is
        deselected.
 
@{b}     RESULT@{ub}
        This method returns GMR_MEACTIVE as long as the gadget is active.
 
        Sets the *msg->gpi_Termination field to CALENDAR_Day, which in turn
        fills in the IntuiMessage->Code field.
 
@EndNode

@Node "GM_HITTEST" "calendar.gadget/GM_HITTEST"
 
@{b}     NAME@{ub}
        GM_HITTEST--Is gadget hit.                              (V42)
 
@{b}     FUNCTION@{ub}
        The GM_HITTEST method is used to determine if the given mouse
        coordinates are within the domain of a day within the calendar.  This
        method overrides the superclass.
 
@{b}     RESULT@{ub}
        This method returns GMR_GADGETHIT if within the domain, otherwise
        zero is returned.
 
        If the gadget is GA_ReadOnly, then zero is always returned.
 
@EndNode

@Node "GM_LAYOUT" "calendar.gadget/GM_LAYOUT"
 
@{b}     NAME@{ub}
        GM_LAYOUT--Calculate relative gadget coordinates.       (V42)
 
@{b}     FUNCTION@{ub}
        The GM_LAYOUT method is used to calculate the domain of the calendar
        and to layout the days of the month.  This method is passed to the
        superclass first.
 
        @{"Gadget" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 213} relativity is fully supported.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "GM_RENDER" "calendar.gadget/GM_RENDER"
 
@{b}     NAME@{ub}
        GM_RENDER--Render the visuals of the calendar.          (V42)
 
@{b}     FUNCTION@{ub}
        The GM_RENDER method is used to render the visuals of the calendar.
        This method overrides the superclass.
 
        If the calendar is disabled, then the ghosting pattern is applied.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "OM_DISPOSE" "calendar.gadget/OM_DISPOSE"
 
@{b}     NAME@{ub}
        OM_DISPOSE--Delete a calendar.gadget object.            (V42)
 
@{b}     FUNCTION@{ub}
        The OM_DISPOSE method is used to delete an instance of the
        calendar.gadget class.  This method is pass to the superclass when
        it has completed.
 
@{b}     RESULT@{ub}
        The object is deleted.  NULL is returned.
 
@EndNode

@Node "OM_NEW" "calendar.gadget/OM_NEW"
 
@{b}     NAME@{ub}
        OM_NEW--Create a calendar.gadget object.                (V42)
 
@{b}     FUNCTION@{ub}
        The OM_NEW method is used to create an instance of the calendar.gadget
        class.  This method is passed to the superclass first.
 
@{b}     ATTRIBUTES@{ub}
        The following attributes can be specified at creation time.
 
        GA_Disabled (BOOL) -- Determines whether the calendar is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  A disabled
            calendar's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern that is rendered in SHADOWPEN.
            Defaults to FALSE.
 
        GA_TextAttr (struct @{"TextAttr" Link "TEXT_INCLUDE:graphics/text.h/Main" 63} *) -- Text attribute for the font to
            use for the labels.
 
        GA_ReadOnly (BOOL) -- Indicate whether calendar has selectable days
            or is for display only.  Defaults to FALSE (selectable days).
 
        CALENDAR_ClockData (struct @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22} *) -- Pointer to a @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22}
            structure (defined in @{"<utility/date.h>" Link "TEXT_INCLUDE:utility/date.h/Main" 0}) used to set the current
            date information, including month, day and year.
 
        CALENDAR_Day (LONG) -- Set the current day of the month.
 
        CALENDAR_FirstWeekday (LONG) -- Sets the first day of the week.
            Defaults to 0, which is Sunday.
 
        CALENDAR_Days (STRPTR *) -- Array of localized column labels,
            starting with Sunday as day[0].  English versions are built
            in.
 
        CALENDAR_Label (BOOL) -- Indicate whether there should be a label
            across the top showing the names of the days of the week.
            Defaults to TRUE.
 
@{b}     RESULT@{ub}
        If the object was created then a pointer to the object is returned,
        otherwise NULL is returned.
 
@EndNode

@Node "OM_SET" "calendar.gadget/OM_SET"
 
@{b}     NAME@{ub}
        OM_SET--Set the attributes of a calendar.gadget object. (V42)
 
@{b}     FUNCTION@{ub}
        The OM_SET method is used to set the attributes of a calendar.gadget.
        This method is passed to the superclass first.
 
@{b}     ATTRIBUTES@{ub}
        The following attributes can be changed at OM_SET or OM_UPDATE.
 
        GA_Disabled (BOOL) -- Determines whether the calendar is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  A disabled
            calendar's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern that is rendered in SHADOWPEN.
            Defaults to FALSE.  Changing the disable state will invoke
            @{"GM_RENDER" Link "GM_RENDER"}.
 
        CALENDAR_ClockData (struct @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22} *) -- Pointer to a @{"ClockData" Link "TEXT_INCLUDE:utility/date.h/Main" 22}
            structure (defined in @{"<utility/date.h>" Link "TEXT_INCLUDE:utility/date.h/Main" 0}) used to set the current
            date information, including month, day and year.  Changing
            the date information will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"} and @{"GM_RENDER" Link "GM_RENDER"}.
 
        CALENDAR_Day (LONG) -- Set the current day of the month.  Changing
            the day will invoke @{"GM_RENDER" Link "GM_RENDER"}.
 
        CALENDAR_Labels (LONG) -- Optional array of day description
            records.  This allows individual control over the appearance
            of each day of the month.  Changing this attribute will
            invoke @{"GM_RENDER" Link "GM_RENDER"}.  If provide, the array must contain 31
            entries.
 
@{b}     RESULT@{ub}
        The class will update the attributes of object.  Changing some
        attributes will result in @{"GM_LAYOUT" Link "GM_LAYOUT"} and/or @{"GM_RENDER" Link "GM_RENDER"} being called.
 
        The return value will be non-zero if the gadget needs to be refreshed.
 
@EndNode

