home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IMSGTEXT.HPP < prev    next >
Text File  |  1993-09-22  |  7KB  |  112 lines
  1. #ifndef _IMSGTEXT_
  2. #define _IMSGTEXT_
  3. /*******************************************************************************
  4. * FILE NAME: imsgtext.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     IMsgtext - Class for loading message text from .msg files.               *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   IBM C/C++ Tools Version 2.01 - Collection Class Library                    *
  12. *   Licensed Materials - Property of IBM                                       *
  13. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  14. *   All Rights Reserved                                                        *
  15. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  16. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  17. *                                                                              *
  18. *******************************************************************************/
  19.  
  20. class IMessageText {
  21. /*******************************************************************************
  22. *  The IMessageText class allows you to load message text                      *
  23. *  from a message (.msg) file.                                                 *
  24. *                                                                              *
  25. *  Typically, an instance of this class is created when an error condition has *
  26. *  been detected, and an exception is going to be thrown.  You can use the     *
  27. *  message text to construct an IException subclass instance.                  *
  28. *                                                                              *
  29. * Example:                                                                     *
  30. *                                                                              *
  31. *  The following example illustrates loading text from a message file and      *
  32. *  using that text to construct and throw an exception.                        *
  33. *                                                                              *
  34. *    Boolean bSuccess = someFunction();                                        *
  35. *    if (!bSuccess)                                                            *
  36. *    {                                                                         *
  37. *       IMessageText myTxt(SOMEFUNCTIONFAIL_ID, "MYMSGFILE");                  *
  38. *       IInvalidRequest exc(myTxt, SOMEFUNCTIONFAIL_ID);                       *
  39. *       ITHROW(exc);                                                           *
  40. *    }                                                                         *
  41. *                                                                              *
  42. *******************************************************************************/
  43. public:
  44. /*------------------------ Constructor/Destructor -----------------------------
  45. | There is only one way to construct instances of this class.  The             |
  46. | IMessageText constructor requires two arguments, the message id and the      |
  47. | name of the message file to retrieve the message from.  The message file     |
  48. | name must include the file extension, typically msg. Up to 9 optional        |
  49. | text strings can be passed for substitution in the message.  The             |
  50. | substitution strings will replace occurrences of %1, %2 in the message if    |
  51. | the number of substitution strings matches the number of %n occurrences in   |
  52. | the message.                                                                 |
  53. | The message will be loaded from program if it is found in a message segment  |
  54. | which has been bound to the .exe.  Otherwise it is searched for in the       |
  55. | specified message file. The search for this file is as follows:              |
  56. |    - The system root directory.                                              |
  57. |    - The current working directory.                                          |
  58. |    - Using the DPATH environment setting.                                    |
  59. |    - Using the APPEND environment setting.                                   |
  60. | If the text cannot be loaded from the message file, the following default    |
  61. | text is provided:  "Unable to load text from message file."                  |
  62. | A copy constructor is also provided.                                         |
  63. ------------------------------------------------------------------------------*/
  64.   IMessageText  ( unsigned long messageId,
  65.                   const char*   messageFileName,
  66.                   const char*   textInsert1 = 0,
  67.                   const char*   textInsert2 = 0,
  68.                   const char*   textInsert3 = 0,
  69.                   const char*   textInsert4 = 0,
  70.                   const char*   textInsert5 = 0,
  71.                   const char*   textInsert6 = 0,
  72.                   const char*   textInsert7 = 0,
  73.                   const char*   textInsert8 = 0,
  74.                   const char*   textInsert9 = 0 );
  75.  
  76.   IMessageText ( const IMessageText& text );
  77.  
  78.   ~IMessageText ( );
  79.  
  80. /*-------------------------------- Accessors -----------------------------------
  81. | The following conversion operator, = operator and functions provide means    |
  82. | of getting and setting the message text from instances of this class:        |
  83. |   operator const char*    - Returns the message text.                        |
  84. |   text                    - Returns the message text.                        |
  85. |   setDefaultText          - Sets the text to a default text string.  The     |
  86. |                             text will only be set if the constructor was     |
  87. |                             unable to load the text for the specified        |
  88. |                             message id.                                      |
  89. |   operator =              - Sets the instance data to the values of the      |
  90. |                             passed IMessageText instance.                    |
  91. ------------------------------------------------------------------------------*/
  92.   operator const char*  () const;
  93.  
  94. const char*
  95.   text ( ) const;
  96.  
  97. IMessageText
  98.  &setDefaultText ( const char*         text ),
  99.  &operator=      ( const IMessageText& text );
  100.  
  101. private:
  102. /*--------------------------------- PRIVATE ----------------------------------*/
  103.  
  104. char
  105.  *pClText;
  106. int
  107.   bClSuccess;
  108.  
  109. }; // IMessageText
  110.  
  111. #endif // _IMSGTEXT_
  112.