home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc Development Framework / ODFDev / ODF / OS / ODUtils / Include / DlogUtil.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-11-08  |  11.6 KB  |  302 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        DlogUtil.h
  3.  
  4.     Contains:    function declarations dialog utility functions
  5.  
  6.     Owned by:    Tantek Çelik
  7.  
  8.     Copyright:    © 1993 - 1995 by Apple Computer, Inc., all rights reserved.
  9.  
  10. */
  11.  
  12. #ifndef _DLOGUTIL_
  13. #define _DLOGUTIL_
  14.  
  15. #ifndef _ODTYPES_
  16. #include <ODTypes.h>
  17. #endif
  18.  
  19. #ifndef _STORUTIL_
  20. #include <StorUtil.h>
  21. #endif
  22.  
  23. #ifndef __DIALOGS__
  24. #include <Dialogs.h>
  25. #endif
  26.  
  27. #ifndef __LISTS__
  28. #include <Lists.h>
  29. #endif
  30.  
  31. #ifndef SOM_Module_OpenDoc_Errors_defined
  32. #include "ErrorDef.xh"
  33. #endif
  34.  
  35. #ifndef _ODDEBUG_
  36. #include "ODDebug.h"
  37. #endif
  38.  
  39. #ifndef __SCRIPT__
  40. #include "Script.h"
  41. #endif
  42.  
  43. #ifndef _UTILERRS_
  44. #include "UtilErrs.h"
  45. #endif
  46.  
  47.  
  48. #ifdef __cplusplus
  49. #define DEFAULT(V) =(V)
  50. extern "C" {
  51. #else
  52. #define DEFAULT(V)
  53. #endif
  54.  
  55. //==============================================================================
  56. // Classes Used in Interface
  57. //==============================================================================
  58.  
  59. class ODSession;
  60. class ODMenuBar;
  61. class DialogScriptData;
  62.  
  63. //==============================================================================
  64. // Psuedo-items representing arrow keys and PageUp etc.
  65. //==============================================================================
  66.  
  67. const char kEnterKey        = 0x03;
  68. const char kReturnKey        = 0x0D;
  69. const char kEscapeKey        = 0x1B;
  70. const char kUpArrowKey        = 0x1E;
  71. const char kDownArrowKey    = 0x1F;
  72.  
  73. const ODSShort kODUpArrowItem = -1000;
  74. const ODSShort kODDownArrowItem = -1001;
  75. const ODSShort kODPageUpArrowItem = -1002;
  76. const ODSShort kODPageDownArrowItem = -1003;
  77. const ODSShort kODHomeArrowItem = -1004;
  78. const ODSShort kODEndArrowItem = -1005;
  79.  
  80. //==============================================================================
  81. // Dialog Utility Macros
  82. //==============================================================================
  83.  
  84. #define ODDisposeRoutineDescriptor(r) \
  85.     if ( !r ) ; else DisposeRoutineDescriptor(r)
  86.  
  87. #define ODDisposeDialog(dlg) \
  88.     if ( !dlg ) ; else DisposeDialog(dlg)
  89.  
  90. #if ODDebug
  91.     inline void ASSERT_CONTROL_ITEM( short itemType )
  92.     {
  93.         itemType &= ~kItemDisableBit;
  94.         ASSERT(itemType>=ctrlItem && itemType<=ctrlItem+resCtrl,kODErrAssertionFailed);
  95.     }
  96. #else
  97.     #define ASSERT_CONTROL_ITEM(T)    do{ } while(0)
  98. #endif
  99.  
  100. #define IS_ARROW_KEY(key)                                                        \
  101.     ((ODBoolean) (((key) >= kODEndArrowItem) && ((key) <= kODUpArrowItem)))        \
  102.  
  103. //==============================================================================
  104. // Dialog Utility Functions
  105. //==============================================================================
  106.  
  107. DialogPtr ODGetNewDialog( Environment*, short id, ODSession*,
  108.                             ODBoolean defaultButtons DEFAULT(kODTrue) );
  109.     // Calls GetNewDialog, with preflighting, and sets things up so the filter
  110.     // proc (below) will work. If defaultButtons is true, will call SetDlog-
  111.     // DefaultItem to set up the standard OK and Cancel buttons.
  112.  
  113. ODSShort ShowAlert(Environment *ev, 
  114.                     ODSShort alertID, 
  115.                     ModalFilterUPP modalFilter, 
  116.                     ODSession *session);
  117.     // Calls Alert, with preflighting, and sets things up so standard OpenDoc 
  118.     // filter procs (below) will work.  This function opens the current library's
  119.     // resource fork, so it must not be called when a resource fork is already
  120.     // open.
  121.  
  122. pascal Boolean ODDialogFilterProc( DialogPtr, EventRecord *, short *item );
  123.     // FilterProc to use for dialogs. Forwards update/activate/null/os events
  124.     // to Dispatcher. Handles std keyboard equivs and movable-modal dialogs.
  125.     // You MUST have created the dialog with ODGetNewDialog!
  126.  
  127. ModalFilterUPP GetODDialogFilter( );
  128.     // Returns global UPP for above filter proc; can be passed directly to
  129.     // ModalDialog() or Alert(). Do not dispose this UPP!
  130.  
  131. pascal Boolean ODArrowKeyFilterProc(DialogPtr dialog, EventRecord *event, short *itemHit);
  132.     // Checks for arrow keys, PageUp, PageDown, Home and End keys, and cmd- and option-
  133.     // modified arrows which are their synonyms.  Sets *itemHit to psuedo-items (negative
  134.     // integers) and returns TRUE when successful, otherwise calls ODButtonKeyFilterProc.
  135.  
  136. ModalFilterUPP GetODArrowKeyFilterProc();
  137.     // Returns global UPP for above filter proc; can be passed directly to
  138.     // ModalDialog(). Do not dispose this UPP!
  139.  
  140. pascal Boolean ODButtonKeyFilterProc(DialogPtr dialog, EventRecord *event, short *itemHit);
  141.     // Checks for return, enter, escape and cmd-period keys (assumes first item is
  142.     // the OK button and the second item is the cancel button).  Call when 
  143.     // ODOutlineDefaultButtonDrawProc  is employed to outline the default buton.
  144.     // The return and enter keys do not exit the dialog if the first item is inactive.
  145.     // Passes other events to ODDialogFilterProc.
  146.  
  147. ModalFilterUPP GetODButtonKeyFilterProc( );
  148.     // Returns global UPP for above filter proc; can be passed directly to
  149.     // ModalDialog(). Do not dispose this UPP!
  150.  
  151. void ODUseCommandKeyStringsResource(short resID);
  152.     // Tells ODButtonKeyFilterProc which STR# resource to use to lookup
  153.     // dialog-specific command keys.  Each string in the STR# resource
  154.     // corresponds by index to each keyable item (button) in the DITL.
  155.     // If the string is "", no command key applies to the item.  Otherwise,
  156.     // the first character of the string is used as the command key code
  157.     // for its corresponding DITL item.  The number of strings in the
  158.     // STR# resource should be less than or equal to the number of items
  159.     // in the DITL resource of the active dialog, or Very Bad Things might
  160.     // happen.
  161.  
  162. void ODDialogBegin( Environment* ev, ODSession* session, 
  163.                     ODMenuBar* currentMenuBar, DialogPtr dialog );
  164.     // Call before ModalDialog, this function removes the Redo menu item so
  165.     // that ModalDialog will know how to enable & disable Cut, Copy & Paste.
  166.     // Must be paired with ODDialogEnd after ModalDialog completes.
  167.  
  168. void ODDialogEnd();
  169.     // Call to cleanly restore the Redo menu item that was deleted in ODDialogBegin.
  170.  
  171. pascal void ODOutlineDefaultButtonDrawProc(DialogPtr theDialog, short theItem);
  172.     // User item draw proc that outlines dialog item 1.
  173.     // Unlike SetDialogDefaultItem, the outline is drawn dim if the button is inactive.
  174.     // If you use this draw proc, be sure to pass kODFalse as the defaultButtons
  175.     // parameter to ODGetNewDialog.
  176.  
  177. UserItemUPP GetODOutlineDefaultButtonDrawProc( );
  178.     // Returns global UPP for above draw proc; can be assigned as an item handle.
  179.     // Do not dispose this UPP!
  180.  
  181. void ODUseDialogScriptData( DialogScriptData* dsd, DialogPtr dialog );
  182.     // set the global to be used by CheckKeyScriptChangeFilterProc
  183.  
  184. pascal ODBoolean CheckKeyScriptChangeFilterProc( DialogPtr dialog,
  185.         EventRecord *event, short *itemHit);
  186.     // Working in cooperation with an instance of DialogScriptData, changes
  187.     // the script/font of a dialog's editable text items when necessary
  188.     // to allow a user to enter text in a non-Roman font.  Since Roman
  189.     // fonts cannot display much non-Roman text, and fonts of one non-Roman
  190.     // script often can't display text of another, we only allow users to
  191.     // switch keyscripts once per dialog, and then only if the starting
  192.     // script is Roman.
  193.     // Note: this filter always returns kODFalse, since it never consumes
  194.     // events.  Call it from your own local filter proc, then pass control
  195.     // to any other filters you need.
  196.  
  197. void EnableOkButton(DialogPtr dlog, ODBoolean enable);
  198.     // Enables or disables the first dialog item and invalidates the area occupied
  199.     // by a default frame around the button.  Should be used to disable the deafult
  200.     // button when ODOutlineDefaultButtonDrawProc is used to outline the button.
  201.  
  202. pascal void DrawGrayBoxItem(DialogPtr theDialog, short theItem);
  203. pascal void DrawItemFrame(DialogPtr theDialog, short theItem);
  204.     // UserItem procs that draw gray or black boxes around items.
  205.  
  206. void FlashButtonItem( DialogPtr dialog, short itemHit );
  207.     // Flash the button in the dialog (used to indicate that a command key
  208.     // combination has selected it.
  209.  
  210. ODBoolean DrawITextInDlogBox( ODIText* itext, const Rect* textRect,
  211.         DialogPtr dlog, ODBoolean tryToTruncate );
  212.     // Given a dialog, a rect and an ODIText*, truncate the text to fit in the
  213.     // rect and then draw it in the dialog.  Return true if any change made to
  214.     // the text (ie. if it was truncated).
  215.  
  216. void ArrowKeyScrollList( ODSShort arrowItem, ListHandle listH,
  217.         ODSShort pageSize, ODSShort lastEntry );
  218.     // Given an "item" representing an up or down arrow or any of the other keys
  219.     // recognized by ODArrowKeyFilterProc above, a ListHandle indicating the list
  220.     // in which scrolling is taking place, pageSize giving the number of entries to
  221.     // be skipped by a "page down" command, and the zero-based index of the last
  222.     // entry in the list, do the right thing for the key selected.  So far this
  223.     // routine is used for lists embedded in dialogs, and it's up to the caller
  224.     // to determine which list is meant if there is more than one.
  225.     // NOTE that nothing happens currently if no list item is selected.  There needs
  226.     // to be a starting point for scrolling.
  227.  
  228. void ReplaceIntoString(ODSShort strResourceID,
  229.                         ConstStr255Param str0,
  230.                         ConstStr255Param str1,
  231.                         Str255 destString);
  232.     // Substitutes str0 for all occurances of "^0", and str1 for "^1", in the 
  233.     // string retrieved from the 'STR ' resource identified by the first parameter.
  234.     // Either str0 or str1 may be null, and str0 or str1 may be the same string
  235.     // as destString.
  236.  
  237. ODIText* GetODITextInd(short resID, short index);
  238.     // Gets string # (index) from the 'STR#' resource given by resID 
  239.     // into an IText* whose script and language codes are those of 
  240.     // the current system script.
  241.     // You MUST first call BeginUsingLibraryResources or CUsingLibraryResources!
  242.  
  243. ODIText* GetODIText(short resID);
  244.     // Gets the 'STR ' resource given by resID into an IText* whose script
  245.     // and language codes are those of the current system script.
  246.     // You MUST first call BeginUsingLibraryResources or CUsingLibraryResources!
  247.  
  248. void SetDialogTextStyle(DialogPtr dlg, short finfResourceID,
  249.         ODScriptCode script);
  250.     // Sets the font, styl, and size of the argument dialog according to the
  251.     // 'finf' resource identified by the second parameter.
  252.     // script parameter overrides what's in the finf resource; intended for
  253.     // language kit cases where the default script is Roman but we need to
  254.     // display text Roman fonts can't handle.  Pass smCurrentScript if you
  255.     // want this param ignored.
  256.  
  257. void SetPopupItemScript(MenuHandle menu, short itemNum, short scriptID);
  258.     // Sets the script of an item in a popup menu, which is assumed to be
  259.     // drawn using the font of the current port.
  260.     // "scriptID" should be a true script code, not an implicit script code
  261.  
  262.  
  263.     // This class provided the state required by clients of
  264.     // CheckKeyScriptChangeFilterProc above.  Typically they'll need
  265.     // to instantiate a member of the class, pass it to ODUseDialogScriptData
  266.     // (also above), and then create and use a custom FilterProc that
  267.     // calls CheckKeyScriptChangeFilterProc.  Since CheckKeyScriptChangeFilterProc
  268.     // always returns false, the custom filter proc should be prepared to
  269.     // call some other filter proc in addition.
  270. const short kMaxNumItems = 32;    // max number of items in a dialog
  271. const short ksmUninited = -4;
  272. class DialogScriptData
  273. {
  274.   public:
  275.     DialogScriptData();
  276.     ODVMethod    ~DialogScriptData();
  277.     ODMethod    void SetScriptAndLockKeyboard();
  278.     ODMethod    void SetDialog(DialogPtr dlg)    { fDialog = dlg; }
  279.     ODMethod    void SetScriptAndLockKeyboard( ODScriptCode script );
  280.     ODMethod    ODBoolean ScriptChanged()    { return fMustUnlock; }
  281.     ODMethod    ODBoolean ItemRedrawn( short item );
  282.     ODMethod    void SetRedrawn( short item );
  283.     ODMethod    ODScriptCode Script()    { return fScript; }
  284.     ODMethod    ODLangCode Language()
  285.             { return GetScriptVariable(fScript, smScriptLang); }
  286.  
  287.   protected:
  288.     ODMethod    void ReleaseLockout();
  289.  
  290.   private:
  291.     ODScriptCode fScript;
  292.     ODBoolean fMustUnlock;
  293.     ODULong fItemRedrawn;            // bit vector of items changed
  294.     DialogPtr fDialog;
  295. };
  296.  
  297. #ifdef __cplusplus
  298. }
  299. #endif
  300.  
  301. #endif // _DLOGUTIL_
  302.