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