home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Developers / apps.to.go / DTS.Lib / DTS.Lib.headers / CtlHandler.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-06-06  |  13.7 KB  |  299 lines  |  [TEXT/MPS ]
  1. #ifndef __BALLOONS__
  2. #include <Balloons.h>
  3. #endif
  4.  
  5. #ifndef __CTLHANDLER__
  6. #define __CTLHANDLER__
  7.  
  8. #ifndef __TYPES__
  9. #include <Types.h>
  10. #endif
  11.  
  12. #ifndef __EVENTS__
  13. #include <Events.h>
  14. #endif
  15.  
  16. #ifndef __WINDOWS__
  17. #include <Windows.h>
  18. #endif
  19.  
  20. #define kScrollEvent    0x8000
  21.  
  22.  
  23.  
  24. short    IsCtlEvent(WindowPtr window, EventRecord *event, ControlHandle *ctl, short *action);
  25.     /*
  26.     **    ¶ Let a control handle the event.
  27.     **
  28.     **    INPUT:    window        Window that owns the controls that the event is to be applied to
  29.     **            event        The event to apply to the controls
  30.     **    OUTPUT:    ctl            The control that ate the event.  If you don't care, pass in nil
  31.     **            action        The action of the control that ate the event.  If you don't
  32.     **                        care, pass in nil.  Note that the action varies with the control
  33.     **                        type.
  34.     **    RESULT:    short        The control ID of the control that ate the event.  If no control
  35.     **                        ate the event, then 0 is returned.  If a document scrollbar ate
  36.     **                        the event, then kScrollEvent is returned.
  37.     **
  38.     **    The purpose of this function is to simplify and standardize control handling within
  39.     **    a window.  Given an event, just call IsCtlEvent, and if it returns a non-0 value,
  40.     **    the value represents the ctlID of the control.
  41.     **    NOTE:    Even if the AppsToGo editor ctlID value is 0, IsCtlEvent will return a
  42.     **            non-0 value.  The value in this case represents the positional value of
  43.     **            the control in the control list.  The first control in the list is
  44.     **            control #1.  Again, this is only for the case where the assigned ctlID
  45.     **            is 0.
  46.     **    This code implements the 7.0 human-interface standards for both TextEdit and
  47.     **    List controls.  These standards include the following features:
  48.     **
  49.     **    1)    Tabbing between TextEdit and List controls within a window.
  50.     **    2)    Displaying what item is active.  The active TextEdit item is indicated
  51.     **        by either a blinking caret, or a selection range.
  52.     **    3)    List positioning via the keyboard.  Entries on the keyboard automatically
  53.     **        select and display the closest List item.  Also, the up and down arrows
  54.     **        scroll through the list.
  55.     **    4)    Document window scrollbars are handled.
  56.     **    5)    Balloon help for window contents is handled (when called with a NULL event).
  57.     **
  58.     **    The main call for handling the control events is:
  59.     **        short    IsCtlEvent(WindowPtr window, EventRecord *event,
  60.     **                           ControlHandle *retCtl, short *retAction);
  61.     **
  62.     **    This call handles the following:
  63.     **        1) Document scrolling.
  64.     **        2) TextEdit control events.
  65.     **        3) List control events.
  66.     **        4) Tabbing (and shirt-tabbing) between TextEdit and list controls.
  67.     **        5) Displaying the selected TextEdit or List control.
  68.     **        6) Buttons.
  69.     **        7) Radio buttons.
  70.     **        8) Check boxes.
  71.     **        9) Popups and other controls.
  72.     **       10) Balloon help for controls.
  73.     **
  74.     **    The document content is scrolled automatically.  The updateRgn is set to include the
  75.     **    area scrolled into view and the window update procedure is automatically called.
  76.     **
  77.     **    TextEdit and List control events are completely handled.  Since the controls are just
  78.     **    containers for TERecords or ListRecords, all other access is up to the application.
  79.     **
  80.     **    Simple buttons are simply tracked.
  81.     **
  82.     **    Radio buttons are updated to reflect the new selection.  Radio buttons are handled as
  83.     **    families.  The refCon field holds the family number.  For any given family, there can
  84.     **    only be one selected radio button.  When a new one is clicked on, the old selected
  85.     **    radio button is deselected automatically.
  86.     **
  87.     **    Check boxes are simply toggled on and off, as there is no family relationship between
  88.     **    checkboxes.
  89.     **
  90.     **    Popups are simply tracked.  To determine what the popup choice is, the popup control
  91.     **    value will have to be retreived.
  92.     **
  93.     **    The return value of IsCtlEvent is non-zero if the event was handled.  The values are
  94.     **    as follows:
  95.     **
  96.     **    0x8000:                IsCtlEvent scrolled the document.  The constant kScrollEvent is
  97.     **                        defined as 0x8000 for this purpose.
  98.     **    0:                    IsCtlEvent didn't handle the event.
  99.     **    any other value:    The control number of the control that handled the event.  Remember that
  100.     **                        a TextEdit control may actually consist of up to 3 controls.  There is
  101.     **                        the main container control for the TERecord.  There may also be 1 or 2
  102.     **                        scrollbar controls that are related to the TERecord.  The control number
  103.     **                        reflects which control was hit.  This allows determination as to whether
  104.     **                        or not the scrollbar was hit.
  105.     **                        For TextEdit and list controls, even if a related scrollbar was hit, the
  106.     **                        control handle returned is the handle for the TextEdit control.
  107.     **
  108.     **    Just because a control number was returned doesn't mean that a control handle was returned.
  109.     **    If an inactive scrollbar is clicked on, then FindControl returns nil, instead of the
  110.     **    control handle (really).  The control that is returned is what FindControl returns, and
  111.     **    therefore it is possibly nil.
  112.     **
  113.     **    For TextEdit and List controls, IsCtlEvent simply calls CTEClick, CTEKey, CLClick or
  114.     **    CLKey.  The value returned as the action depends on which function was called.  The
  115.     **    true/false returned by these functions as to whether or not the control handled the event
  116.     **    is expanded to be the control number.  If false is returned by any of these functions, then
  117.     **    IsCtlEvent returns 0 for the control number.
  118.     **
  119.     **    IsCtlEvent has no way of determining if you are actually using TextEdit or List controls.
  120.     **    Since it has to make function calls service these controls, code may get linked into your
  121.     **    application that you don't need.  To prevent this, IsCtlEvent calls the appropriate
  122.     **    functions by function pointer.  The default functions are just stub functions that return
  123.     **    appropriate results as if there were no such controls.  This allows IsCtlEvent to handle
  124.     **    the case where these controls aren't used without linking in a bunch of code.
  125.     **
  126.     **    So what about the case where you DO want to use these controls?  To create one of these
  127.     **    controls, you have to call either CTENew or CLNew, for TextEdit and List controls,
  128.     **    respectively.  (Or, if you are using the AppsToGo program editor, you simply create them
  129.     **    in a fashion similar to ResEdit.)
  130.     **
  131.     **    When CTENew is called, it calls CTEInitialize.  CTEInitialize replaces all
  132.     **    of the stub function procedure pointers with pointers to the actual functions.
  133.     **    If you call CTENew, then CTENew will get linked in.  Since CTENew calls
  134.     **    CTEInitialize, CTEInitialize will get linked in.  Since it references the actual
  135.     **    code, the actual code will get linked in.  This allows you to not have to worry about
  136.     **    specific implementations linking in too much code.  If you call it, it will link.  The
  137.     **    above process is also done for List controls. */
  138.  
  139.  
  140.  
  141. short    CNum2Ctl(WindowPtr window, short ctlNum, ControlHandle *ctl);
  142.     /*
  143.     **    ¶ Convert a control number to a control handle.
  144.     **
  145.     **    INPUT:    window        Window that owns the control list to be scanned.
  146.     **            ctlNum        ID of the control to search for.
  147.     **    OUTPUT:    ctl            If a control is found with the correct ID, it is returned here.
  148.     **    RESULT:    short        ID of found control (archaic)
  149.     **
  150.     **    AppsToGo extends the control record.  This means that, among other things, controls
  151.     **    can have a fixed control ID.  If a control has a style, and the ctlID field if the 
  152.     **    style is non-zero, then that control has a fixed control ID.  Due to this, CNum2Ctl
  153.     **    first scans all of the controls for a control with a style that has the designated
  154.     **    ctlID.  If one is found, then that's the control returned.  If none is found, then
  155.     **    the behavior for this function is as before (for the purpose of backwards-compatibility).
  156.     **
  157.     **    The way that this function used to work is:
  158.     **
  159.     **        It simply walks the window's control list counting down until it has reached
  160.     **        the right control number.  It also returns the number of controls traversed.
  161.     **        While often this will be the same as the control number passed in, if the
  162.     **        number passed in is greater than the number of controls in the list, then
  163.     **        the number returned is the number of controls in the list. */
  164.  
  165.  
  166.  
  167. short    Ctl2CNum(ControlHandle ctl);
  168.     /*
  169.     **    ¶ Convert a control handle to a control number.
  170.     **
  171.     **    INPUT:    ctl        Control handle to convert to an ID.
  172.     **    RESULT:    short    The ID of the control passed in.
  173.     **
  174.     **    This function converts a control handle to a control number.  This allows you to convert
  175.     **    what is normally a runtime variable into something that can be equated to a constant,
  176.     **    thus allowing you to code your control handling into case statements.  This function
  177.     **    does the opposite of CNum2Ctl. */
  178.  
  179.  
  180.  
  181. void    DoCtlActivate(WindowPtr window);
  182.     /*
  183.     **    ¶ Reactivate a TextEdit or List control.
  184.     **
  185.     **    INPUT:    window        Window whose TextEdit or List control is to be reactivated
  186.     **
  187.     **    This reactivates the TextEdit or List control that was active for a particular window.
  188.     **    When a window is moved from the front, the controls are supposed to become inactive.
  189.     **    This is handled, but the control that was last active for a window is remembered.
  190.     **    When the window is brought to the front, that particular control can be reactivated
  191.     **    by calling DoCtlActivate. */
  192.  
  193.  
  194.  
  195. void    GetCheckBoxValues(WindowPtr window, Boolean checkBoxVal[]);
  196.     /*
  197.     **    ¶ Return checkBox values, en-masse.
  198.     **
  199.     **    INPUT:    window            Window whose control list is to be scanned for
  200.     **                            checkBox controls.
  201.     **    OUTPUT:    checkBoxVal        An array that is to receive the value of the checkBox
  202.     **                            controls in the windowList.  It is the caller's
  203.     **                            responsibility to guarantee that the array is large enough.
  204.     **                            This function will use one array element for every
  205.     **                            checkBox control found in the control list of the window.
  206.     **
  207.     **    Call this to scan the window’s control list for checkbox controls.  For each one
  208.     **    found, you need an element in the array.  The entire control list is scanned.  The
  209.     **    control ID is ignored.  Only the order in the control list is relavent.  What this
  210.     **    means in terms of the AppsToGo editor is that the checkbox control that is back-most
  211.     **    has it’s value returned in element 0. */
  212.  
  213.  
  214.  
  215. short    GetRadioButtonChoice(WindowPtr window, short famNum);
  216.     /*
  217.     **    ¶ Determine which radio button is selected in a family.
  218.     **
  219.     **    INPUT:    window        Window containing the family of radio buttons.
  220.     **            famNum        The family number of the radio buttons.
  221.     **    RESULT:    short        Which radio button in the family that is selected.
  222.     **
  223.     **    Given a particular family number, return which radio button is the currently selected
  224.     **    button.  If the requested family isn't found, or there are no selected radio buttons
  225.     **    in the family, -1 is returned.  If the family is found, the control number of the the
  226.     **    selected radio button minus the control number of the first in the family is returned.
  227.     **    ••• The first in the family is the control with the smallest ID. •••
  228.     **    This means that for most situations, you will simply get an integer from 0-N for the
  229.     **    radio button selection, as in most cases, the radio button ID's will be sequential in
  230.     **    the control list. */
  231.  
  232.  
  233.  
  234. ControlHandle    CDataNext(WindowPtr window, ControlHandle ctl);
  235.     /*
  236.     **    ¶ Iterate to the next data control.
  237.     **
  238.     **    INPUT:    window            Window containing control list to scan.
  239.     **            ctl                Control to start search from (nil for beginning of list)
  240.     **    RESULT:    ControlHandle    Next data control in list (nil indicates no more in list)
  241.     **
  242.     **    When a set of controls defined with the AppsToGo editor is added to a window, an
  243.     **    additional Data control is also added.  The purpose of the Data control is to keep
  244.     **    track of which controls were added as a set of controls.  (The Data control "groups"
  245.     **    the set of controls.)  CDataNext allows you to get the next data control out of the
  246.     **    window's control list.  (Normally you won't need this function.) */
  247.  
  248.  
  249.  
  250. Boolean    ControlBalloonHelp(WindowPtr window, short modifiers, Point mouseLoc);
  251.     /*
  252.     **    ¶ Handle balloon help for controls.
  253.     **
  254.     **    INPUT:    window            Window containing controls that may have balloon help info.
  255.     **            modifiers        This is in case the application is using fast balloons.
  256.     **            mouseLoc        Current mouse location, in global coordinates.
  257.     **    RESULT:    Boolean            True if a balloon was displayed.
  258.     **
  259.     **    This function is actually in Help.c, but it is specifically for managing
  260.     **    balloon help for controls.  IsCtlEvent calls it, although you can call it
  261.     **    yourself, if you want.  (There shouldn't be any reason for an application
  262.     **    to call this directly. */
  263.  
  264.  
  265.  
  266. ControlHandle    ControlBalloonMessage(WindowPtr window, Point mouseLoc, HMMessageRecord *msg,
  267.                                       Rect *msgRct, short *pos, short *hrctID, short *itemID);
  268.     /*
  269.     **    ¶ Get the balloon help record for a control.
  270.     **
  271.     **    INPUT:    window            Window containing controls that may have balloon help info.
  272.     **            mouseLoc
  273.     **    OUTPUT:    msg                The Balloon Help message record.  This is what should be
  274.     **                            displayed in the balloon.
  275.     **            msgRct            The rect of the control the help message relates to.
  276.     **            pos                The balloon position.
  277.     **            hrctID            The 'hrct' resource ID.
  278.     **            itemID            The 'hrct' resource item ID.
  279.     **    RESULT:    ControlHandle    The control the help is for. */
  280.  
  281.  
  282.  
  283. PicHandle        BalloonText2PICT(WindowPtr window, HMMessageRecord *msg);
  284.     /*
  285.     **    ¶ Convert the too-big text to a PICT so it can be displayed.
  286.     **
  287.     **    INPUT:    window            Window that the balloon help is for.
  288.     **            msg                The Balloon Help message record.  (May or may not be a text record.)
  289.     **    RESULT:    PicHandle        If the Balloon Help record is text, then a PicHandle is created
  290.     **                            that contains the text.
  291.     **
  292.     **    This function converts a Balloon Help text message into a PicHandle.  This is because
  293.     **    Balloon Help only automatically works for text strings less than 255 characters.
  294.     **    Longer balloons need to be done with the PICT resource type.  This function converts
  295.     **    text messages into a PICT so that long text can be used without having to create
  296.     **    a PICT. */
  297.  
  298. #endif
  299.