═══ 1. Data Type and Exception Classes ═══ Provide support for the exceptions, trace output, messages, strings, and notifications used by the applications you develop. ═══ 1.1. Class Hierarchy ═══ IBase ├─IBitFlag ├─IDate ├─INotificationEvent ├─IPair │ ├─IPoint │ ├─IRange │ └─ISize ├─IPointArray ├─IRectangle ├─IReference ├─IString │ └─I0String ├─IStringParser ├─IStringParser::SkipWords ├─ITime └─IVBase ├─IObserverList::Cursor ├─IBuffer │ └─IDBCSBuffer ├─IErrorInfo │ ├─ICLibErrorInfo │ ├─IGUIErrorInfo │ ├─ISystemErrorInfo │ └─IXLibErrorInfo ├─INotifier │ └─IStandardNotifier ├─IObserver ├─IObserverList ├─IRefCounted ├─IStringTest │ └─IStringTestMemberFn └─ITrace IException ├─IAccessError ├─IAssertionFailure ├─IDeviceError ├─IInvalidParameter ├─IInvalidRequest └─IResourceExhausted ├─IOutOfMemory ├─IOutOfSystemResource └─IOutOfWindowResource IExceptionLocation IMessageText IStringEnum IException::TraceFn IBase::Version ═══ 1.2. I0String ═══ Description Derivation Constructors Public Functions Protected Functions Public Data Protected Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - I0String ═══ IBase │ IString │ I0String Inherited by none. ═══ Class Description - I0String ═══ i0string.hpp Objects of the I0String class are functionally equivalent to objects of the class IStringwith one major distinction: I0Strings are indexed starting at 0 instead of 1. Note: A consequence of starting indexes at 0 is that you can no longer use the search functions as if they were Boolean. For example: a0String.indexOf( anotherString ) != a0String.includes( anotherString ). You can freely intermix IStrings and I0Strings in a program. You can assign objects of one class values of the other type. You can pass objects of either class as parameters to functions requiring the other type. Warning: UINT_MAX is a reserved value for I0String. If you use UINT_MAX for the startPos parameter in I0String functions, unpredictable results can occur. ═══ Public Functions - I0String ═══ Constructors I0String ~I0String Editing change insert overlayWith remove Queries charType operator [] subString Searches indexOf indexOfAnyBut indexOfAnyOf lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf occurrencesOf Word Operations indexOfPhrase indexOfWord Inherited Members IString asDebugInfo asDouble asInt asString asUnsigned b2c b2d b2x c2b c2d c2x center change charType copy d2b d2c d2x includes includesDBCS includesMBCS includesSBCS indexOf indexOfAnyBut indexOfAnyOf indexOfPhrase indexOfWord insert isAbbreviationFor isAlphabetic isAlphanumeric isASCII isBinaryDigits isControl isDBCS isDigits isGraphics isHexDigits isLike isLowerCase isMBCS isPrintable isPunctuation isSBCS isUpperCase isValidDBCS isValidMBCS isWhiteSpace lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf leftJustify length lengthOfWord lineFrom lowerCase numWords occurrencesOf operator & operator &= operator + operator += operator = operator char * operator signed char * operator unsigned char * operator [] operator ^ operator ^= operator | operator |= operator ~ overlayWith remove removeWords reverse rightJustify size space strip stripBlanks stripLeading stripLeadingBlanks stripTrailing stripTrailingBlanks subString translate upperCase word wordIndexOfPhrase words x2b x2c x2d IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ I0String - Constructors ═══ You can construct objects of this class in the following ways: Construct a NULL string. Construct a string with the ASCII representation of a given numeric value, supporting all variations of integer and double. Construct a string with a copy of the specified character data, supporting ASCIIZ strings, characters, and IStrings. The character data passed is converted to its ASCII representation. Construct a string with contents that consist of copies of up to three buffers of arbitrary data (void*). Optionally, you only need to provide the length, in which case the IString contents are initialized to a specified pad character. The default character is a blank. These constructors can throw exceptions under the following conditions: Memory allocation errors Many factors dynamically allocate space and these allocation requests may fail. If so, the User Interface Class Library translates memory allocation errors into exceptions. Generally, such errors do not occur until you allocate an astronomical amount of storage. Out-of-range errors These occur if you attempt to construct an IString with a length greater than UINT_MAX. ═══ I0String - Editing ═══ These members are reimplemented to treat the position arguments as 0-based. ═══ I0String - Index Mapping ═══ Use these members to convert arguments and results to the proper index base: 1 for arguments (because it relies on IString) and 0 for results (because it is 0 based itself). ═══ I0String - Queries ═══ These members are overridden to permit specification of the index as a 0-based value. ═══ I0String - Searches ═══ These members are reimplemented to treat the starting position of the search as a 0-based index. ═══ I0String - Word Operations ═══ These members are reimplemented to treat the result index as 0-based. ═══ Protected Functions - I0String ═══ Index Mapping adjustArg adjustResult Inherited Members IString applyBitOp buffer change data defaultBuffer findPhrase indexOfWord initBuffer insert isAbbrevFor isLike lengthOf occurrencesOf overlayWith setBuffer strip translate ═══ Public Data - I0String ═══ Searches notFound ═══ Protected Data - I0String ═══ Inherited Members IString maxLong null nullBuffer zero IBase recoverable unrecoverable ═══ 1.2.1. I0String::adjustArg ═══ Adjusts the specified index from 0- to 1-based. protected: static unsigned adjustArg(unsigned index); ═══ 1.2.2. I0String::adjustResult ═══ Adjusts a function result from 1- to 0-based. protected: static unsigned adjustResult(unsigned index); ═══ 1.2.3. I0String::change ═══ Changes occurrences of a specified pattern to a specified replacement string. You can specify the number of changes to perform. The default is to change all occurrences of the pattern. You can also specify the position in the receiver at which to begin. The parameters are the following: inputString The pattern string as a reference to an object of type IString. The library searches for the pattern string within the receiver's data. pInputString The pattern string as NULL-terminated string. The library searches for the pattern string within the receiver's data. outputString The replacement string as a reference to an object of type IString. It replaces the occurrences of the pattern string in the receiver's data. pOutputString The replacement string as a NULL-terminated string. It replaces the occurrences of the pattern string in the receiver's data. startPos The position to start the search at within the receiver's data. The default is 0. numChanges The number of patterns to search for and change. The default is UINT_MAX, which causes changes to all occurrences of the pattern. Overload 1 public: I0String& change( const IString& aPattern, const char* pReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 2 public: I0String& change( const IString& aPattern, const IString& aReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 3 public: I0String& change( const char* pPattern, const IString& aReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 4 public: I0String& change( const char* pPattern, const char* pReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 5 public: static I0String change( const IString& aString, const IString& inputString, const IString& outputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 6 public: static I0String change( const IString& aString, const IString& inputString, const char* pOutputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 7 public: static I0String change( const IString& aString, const char* pInputString, const IString& outputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 8 public: static I0String change( const IString& aString, const char* pInputString, const char* pOutputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX); ═══ 1.2.4. I0String::charType ═══ Returns the type of the character at the specified index. public: IStringEnum::CharType charType(unsigned index) const; ═══ 1.2.5. I0String::I0String ═══ You can construct objects of this class in the following ways: Construct a NULL string. Construct a string with the ASCII representation of a given numeric value, supporting all variations of integer and double. Construct a string with a copy of the specified character data, supporting ASCIIZ strings, characters, and IStrings. The character data passed is converted to its ASCII representation. Construct a string with contents that consist of copies of up to three buffers of arbitrary data (void*). Optionally, you only need to provide the length, in which case the IString contents are initialized to a specified pad character. The default character is a blank. These constructors can throw exceptions under the following conditions: Memory allocation errors Many factors dynamically allocate space and these allocation requests may fail. If so, the User Interface Class Library translates memory allocation errors into exceptions. Generally, such errors do not occur until you allocate an astronomical amount of storage. Out-of-range errors These occur if you attempt to construct an IString with a length greater than UINT_MAX. Overload 1 public: I0String(char); Construct a string with a copy of the character. The string length is set to 1. Overload 2 public: I0String(); Construct a NULL string. Overload 3 public: I0String(const IString& aString); Construct a string with a copy of the specified IString. Overload 4 public: I0String(int); Construct a string with the ASCII representation of an integer numeric value. Overload 5 public: I0String(unsigned); Construct a string with the ASCII representation of an unsigned numeric value. Overload 6 public: I0String(long); Construct a string with the ASCII representation of a long numeric value. Overload 7 public: I0String(unsigned long); Construct a string with the ASCII representation of an unsigned long numeric value. Overload 8 public: I0String(short); Construct a string with the ASCII representation of a short numeric value. Overload 9 public: I0String(unsigned short); Construct a string with the ASCII representation of an unsigned short numeric value. Overload 10 public: I0String(double); Construct a string with the ASCII representation of a double numeric value. Overload 11 public: I0String(unsigned char); Construct a string with a copy of the unsigned character. The string length is set to 1. Overload 12 public: I0String(signed char); Construct a string with a copy of the signed character. The string length is set to 1. Overload 13 public: I0String(const char*); Construct a string with a copy of the specified ASCIIZ string. Overload 14 public: I0String(const unsigned char*); Construct a string with a copy of the specified unsigned ASCIIZ string. Overload 15 public: I0String(const signed char*); Construct a string with a copy of the specified signed ASCIIZ string. Overload 16 public: I0String( const void* pBuffer1, unsigned lenBuffer1, char padCharacter = ' '); Construct a string with contents from one buffer of arbitrary data (void*). Overload 17 public: I0String( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, char padCharacter = ' '); Construct a string with contents from two buffers of arbitrary data (void*). Overload 18 public: I0String( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, const void* pBuffer3, unsigned lenBuffer3, char padCharacter = ' '); Construct a string with contents from three buffers of arbitrary data (void*). ═══ 1.2.6. I0String::indexOf ═══ Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, 0 is returned. In addition to IStrings, you can also specify a single character or an IStringTest. Overload 1 public: unsigned indexOf( const char* pString, unsigned startPos = 0) const; Overload 2 public: unsigned indexOf( const IString& aString, unsigned startPos = 0) const; Overload 3 public: unsigned indexOf( char aCharacter, unsigned startPos = 0) const; Overload 4 public: unsigned indexOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.2.7. I0String::indexOfAnyBut ═══ Returns the index of the first character of the receiver that is not in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that fails the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyBut( const IString& aString, unsigned startPos = 0) const; Overload 2 public: unsigned indexOfAnyBut( const char* pValidChars, unsigned startPos = 0) const; Overload 3 public: unsigned indexOfAnyBut( char validChar, unsigned startPos = 0) const; Overload 4 public: unsigned indexOfAnyBut( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.2.8. I0String::indexOfAnyOf ═══ Returns the index of the first character of the receiver that is a character in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that passes the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyOf( const char* pSearchChars, unsigned startPos = 0) const; Overload 2 public: unsigned indexOfAnyOf( const IString& searchChars, unsigned startPos = 0) const; Overload 3 public: unsigned indexOfAnyOf( char searchChar, unsigned startPos = 0) const; Overload 4 public: unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.2.9. I0String::indexOfPhrase ═══ Returns the position of the first occurrence of the specified phrase in the receiver. If the phrase is not found, 0 is returned. public: unsigned indexOfPhrase( const IString& wordString, unsigned startWord = 1) const; ═══ 1.2.10. I0String::indexOfWord ═══ Returns the index of the specified white-space-delimited word in the receiver. If the word is not found, 0 is returned. public: unsigned indexOfWord(unsigned wordNumber) const; ═══ 1.2.11. I0String::insert ═══ Inserts the specified string at the specified location. Overload 1 public: static I0String insert( const IString& aString, const char* pInsert, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' '); Overload 2 public: I0String& insert( const IString& aString, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' '); Overload 3 public: I0String& insert( const char* pString, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' '); Overload 4 public: static I0String insert( const IString& aString, const IString& anInsert, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' '); ═══ 1.2.12. I0String::lastIndexOf ═══ Returns the index of the last occurrence of the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The returned value is in the range 0 <= x <= startPos or I0String::notFound. The default of UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOf( const char* pString, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 2 public: unsigned lastIndexOf( const IString& aString, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 3 public: unsigned lastIndexOf( char aCharacter, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 4 public: unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 )) const; ═══ 1.2.13. I0String::lastIndexOfAnyBut ═══ Returns the index of the last character not in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 2 public: unsigned lastIndexOfAnyBut( const IString& validChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 3 public: unsigned lastIndexOfAnyBut( const char* pValidChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 4 public: unsigned lastIndexOfAnyBut( char validChar, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 )) const; ═══ 1.2.14. I0String::lastIndexOfAnyOf ═══ Returns the index of the last character in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 2 public: unsigned lastIndexOfAnyOf( const IString& searchChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 3 public: unsigned lastIndexOfAnyOf( const char* pSearchChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 )) const; Overload 4 public: unsigned lastIndexOfAnyOf( char searchChar, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 )) const; ═══ 1.2.15. I0String::notFound ═══ You use this static constant in conjunction with the searching functions. It specifies the value searching functions return indicating the search failed. public: static const unsigned notFound; ═══ 1.2.16. I0String::occurrencesOf ═══ Returns the number of occurrences of the specified IString, char*, char, or IStringTest. If you just want a Boolean test, this is slower than IString::indexOf. Overload 1 public: unsigned occurrencesOf( const IString& aString, unsigned startPos = 0) const; Overload 2 public: unsigned occurrencesOf( const char* pString, unsigned startPos = 0) const; Overload 3 public: unsigned occurrencesOf( char aCharacter, unsigned startPos = 0) const; Overload 4 public: unsigned occurrencesOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.2.17. I0String::operator [] ═══ Returns a reference to the specified character of the string. Note: If you call the non-const version of this function with an index beyond the end, the function extends the string. Overload 1 public: const char& operator [](unsigned index) const; Overload 2 public: char& operator [](unsigned index); ═══ 1.2.18. I0String::overlayWith ═══ Replaces a specified portion of the receiver's contents with the specified string. The overlay starts in the receiver's data at the index, which defaults to 0. If index is beyond the end of the receiver's data, it is padded with the pad character (padCharacter). Overload 1 public: I0String& overlayWith( const IString& aString, unsigned index = 0, char padCharacter = ' '); Overload 2 public: I0String& overlayWith( const char* pString, unsigned index = 0, char padCharacter = ' '); Overload 3 public: static I0String overlayWith( const IString& aString, const IString& anOverlay, unsigned index = 0, char padCharacter = ' '); Overload 4 public: static I0String overlayWith( const IString& aString, const char* pOverlay, unsigned index = 0, char padCharacter = ' '); ═══ 1.2.19. I0String::remove ═══ Deletes the specified portion of the string (that is, the substring) from the receiver. You can use this function to truncate an IString object at a specific position. For example: aString.remove(8); removes the substring beginning at index 8 and takes the rest of the string as a default. Overload 1 public: static I0String remove( const IString& aString, unsigned startPos); Overload 2 public: I0String& remove(unsigned startPos); Overload 3 public: I0String& remove(unsigned startPos, unsigned numChars); Overload 4 public: static I0String remove( const IString& aString, unsigned startPos, unsigned numChars); ═══ 1.2.20. I0String::subString ═══ Returns the specified portion of the string (that is, the substring) of the receiver. The parameters are the following: startPos The starting position of the substring being extracted. If this position is beyond the end of the data in the receiver, this function returns a NULL IString. length The length of the substring to be extracted. If the length extends beyond the end of the receiver's data, the returned IString is padded to the specified length with padCharacter. If you do not specify length and it defaults, this function uses the rest of the receiver's data starting from startPos for padding. padCharacter The character the function uses as padding if the requested length extends beyond the end of the receiver's data. The default padCharacter is a blank. You can use this function to truncate an IString object at a specific position. For example: aString = aString.subString(0, 7); returns the substring concluding with index 7 and discards the rest of the string. Overload 1 public: I0String subString(unsigned startPos) const; Overload 2 public: I0String subString( unsigned startPos, unsigned len, char padCharacter = ' ') const; ═══ 1.2.21. I0String::~I0String ═══ public: virtual ~I0String(); ═══ 1.3. IAccessError ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IAccessError ═══ IException │ IAccessError Inherited by none. ═══ Class Description - IAccessError ═══ iexcbase.hpp Objects of the IAccessError class represent an exception. When a member function makes a request of the operating system or the presentation system that the system cannot satisfy, the member function creates and throws an object of the IAccessError class. If the operating system or the presentation system cannot satisfy the request due to resource exhaustion, member functions create and throw objects of the class IResourceExhausted. Note: Typically, if no other exception fits an error condition, the User Interface Class Library creates and throws an object of the IAccessError class. ═══ Public Functions - IAccessError ═══ Constructors IAccessError Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IAccessError - Constructors ═══ You can construct objects of this class. ═══ IAccessError - Exception Type ═══ Exception Type members provide support for determining the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IAccessError ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.3.1. IAccessError::IAccessError ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IAccessError( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.3.2. IAccessError::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.4. IAssertionFailure ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IAssertionFailure ═══ IException │ IAssertionFailure Inherited by none. ═══ Class Description - IAssertionFailure ═══ iexcbase.hpp Objects of the IAssertionFailure class represent an exception. The IASSERT macro expands to create and throw an object of the IAssertionFailure class if the specified condition is not met. An assertion is a debugging tool you can use to assure a condition is true. The class IException describes IASSERT and the other exception-handling macros. ═══ Public Functions - IAssertionFailure ═══ Constructors IAssertionFailure Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IAssertionFailure - Constructors ═══ You can construct objects of this class. ═══ IAssertionFailure - Exception Type ═══ Exception Type members provide support for determining the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IAssertionFailure ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.4.1. IAssertionFailure::IAssertionFailure ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macro IASSERT. The User Interface Class Library provides this macro to make creating exceptions easier for you. public: IAssertionFailure( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.4.2. IAssertionFailure::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.5. IBase ═══ Description Derivation Public Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IBase ═══ Inherits from none. Inherited by: IAccelerator IBitFlag ICnrAllocator ICollectionViewConstants ICoordinateSystem ICritSec IDate IDDE IDDEActiveServer IEventData IEventParameter1 IEventParameter2 IEventResult IFileDialog::Settings IFontDialog::Settings IFrameExtension IGraphicBundle IHandle IHelpWindow::Settings IHighEventParameter ILowEventParameter IMenuItem IMMAudioBuffer INotificationEvent IPair IPointArray IProcedureAddress IRectangle IReference IResourceId IString IStringGenerator IStringParser IStringParser::SkipWords ISWP ISWPArray ITime ITransformMatrix IVBase ═══ Class Description - IBase ═══ ibase.hpp The IBase class encapsulates the set of names that otherwise would be in global scope. All the classes in the library inherit from this class. Thus, you can use the types and enumeration values defined here in those classes without the qualifying IBase:: prefix. Other code, not within the scope of IBase, must use either the qualified names or the simplified synonyms which the User Interface Class Library declares in ISYNONYM.HPP. ═══ Public Functions - IBase ═══ Diagnostics asDebugInfo asString version Messages messageFile messageText setMessageFile ═══ IBase - Boolean Definitions ═══ This class declares a global Boolean type and enumeration, both of which are used throughout the library. ═══ IBase - Diagnostics ═══ Use these members to provide diagnostic information. ═══ IBase - Exception Severity ═══ These data members are provided as synonyms for the IException::Severity enumeration, which is used when constructing an IException object or an object of one of its derived classes. ═══ IBase - Messages ═══ Use these members to query and change the message file that contains text used by the class library when throwing exceptions. ═══ Protected Data - IBase ═══ Exception Severity recoverable unrecoverable ═══ 1.5.1. IBase::asDebugInfo ═══ This function obtains the diagnostic version of an object's contents. You use this to retrieve an IString representing a hex pointer to the object. public: IString asDebugInfo() const; ═══ 1.5.2. IBase::asString ═══ This function obtains the standard version of an object's contents. public: IString asString() const; ═══ 1.5.3. IBase::messageFile ═══ This function returns the name of the message file used to load library exception text. public: static char* messageFile(); Presentation Manager: If you previously called setMessageFile with the name of a message file, the file's name is returned. Otherwise, the library checks the environment variable ICLUI MSGFILE for the message file name. You can set the environment variable using: SET ICLUI MSGFILE=mymsgfile.msg You must specify the file extension, typically .MSG. If you have not set the environment variable, the library uses the default message file (CPPOOC3U.MSG). Motif: If you previously called setMessageFile with the name of a message file, the file's name is returned. The default file name is ibmcl.cat. ═══ 1.5.4. IBase::messageText ═══ Returns the message text associated with the specified message ID. You can specify up to nine optional text strings to insert into the message. public: static IMessageText messageText( unsigned long messageId, const char* textInsert1 = 0, const char* textInsert2 = 0, const char* textInsert3 = 0, const char* textInsert4 = 0, const char* textInsert5 = 0, const char* textInsert6 = 0, const char* textInsert7 = 0, const char* textInsert8 = 0, const char* textInsert9 = 0); Presentation Manager: If the message is found in a message segment that has been bound to the .EXE, the message is loaded from the application. Otherwise, the message is searched for in the message file described before. The search order for this file is as follows: The system root directory The current working directory Using the DPATH environment setting Using the APPEND environment setting Motif: The AIX release uses the message catalog file ibmcl.cat. You must add the /nls subdirectory to your NLSPATH environment variable so the User Interface Class Library can access the message catalog. In the Korn Shell, put the following statement in your .profile file: export NLSPATH=/nls/%N:$NLSPATH where is the directory in which you installed the User Interface Class Library. ═══ 1.5.5. IBase::recoverable ═══ Synonym for IException::recoverable. Use this when constructing an IException object or one of its subclasses: protected: static IException::Severity recoverable; ═══ 1.5.6. IBase::setMessageFile ═══ Sets the message file from which the class library loads its exception text. The name must include the file extension. public: static void setMessageFile(const char* msgFileName); ═══ 1.5.7. IBase::unrecoverable ═══ Synonym for IException::unrecoverable. Use this when constructing an IException object or one of its subclasses: protected: static IException::Severity unrecoverable; ═══ 1.5.8. IBase::version ═══ Returns the User Interface Class Library version using the major and minor data members of the IBase::Version data structure. The minor number is incremented to indicate the service level. This is a static member function. public: static Version version(); ═══ Nested Types - IBase ═══ Enumerations BooleanConstants Type Definitions Boolean ═══ Enums - BooleanConstants ═══ enum BooleanConstants { false=0, true=1 }; The User Interface Class Library provides this enumeration to define constant values for false and true. Never use true for an equality test because you should consider any nonzero value to be true. This constant provides a useful mnemonic for setting a Boolean. ═══ Type Definition - IBase::Boolean ═══ typedef int Boolean; General true or false type used as an argument or return value for many member functions. ═══ 1.6. IBase::Version ═══ Description Derivation Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IBase::Version ═══ Inherits from none. Inherited by none. ═══ Class Description - IBase::Version ═══ ibase.hpp This structure (data type) defines the version specifier, comprised of major and minor version numbers. ═══ IBase::Version - Version Data ═══ Encapsulates versioning data for class library objects. ═══ Public Data - IBase::Version ═══ Version Data major minor ═══ 1.6.1. IBase::Version::major ═══ The major version level of the library, it is incremented by 1 for each new release within a version. public: unsigned short major; ═══ 1.6.2. IBase::Version::minor ═══ The minor version level of the library, it starts at 0 for each major version level and is incremented by 1 for each CSD. public: unsigned short minor; ═══ 1.7. IBitFlag ═══ Description Derivation Public Functions Protected Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IBitFlag ═══ IBase │ IBitFlag Inherited by: I3StateCheckBox::Style IAnimatedButton::Style IBaseComboBox::Style IBaseListBox::Style IBaseSpinButton::Style IBitmapControl::Style IButton::Style ICanvas::Style ICheckBox::Style ICircularSlider::Style IComboBox::Style IContainerControl::Attribute IContainerControl::Style IControl::Style ICustomButton::Style IDMImage::Style IDrawingCanvas::Style IEntryField::Style IFileDialog::Style IFontDialog::Style IFrameWindow::Style IGraphicPushButton::Style IGroupBox::Style IIconControl::Style IListBox::Style IListBoxDrawItemHandler::DrawFlag IMenu::Style IMenuBar::Style IMenuDrawItemHandler::DrawFlag IMenuItem::Attribute IMenuItem::Style IMessageBox::Style IMultiCellCanvas::Style IMultiLineEdit::Style INotebook::PageSettings::Attribute INotebook::Style INumericSpinButton::Style IOutlineBox::Style IProgressIndicator::Style IPushButton::Style IRadioButton::Style IScrollBar::Style ISetCanvas::Style ISlider::Style ISpinButton::Style ISplitCanvas::Style IStaticText::Style ITextSpinButton::Style IToolBar::Style IToolBarButton::Style IToolBarContainer::Style IViewPort::Style IWindow::Style ═══ Class Description - IBitFlag ═══ ibitflag.hpp The IBitFlag class is the abstract base class for the bitwise styles and attributes used by window and control classes in the User Interface Class Library. Because this class in an abstract base class, you cannot create objects of this class. Deriving Classes from IBitFlag Typically, you can declare classes derived from IBitFlag by using the macros that accompany this class. Optionally, these macros lets you: Construct objects of one derived class from objects of another class derived from IBitFlag. Combine objects of one derived class with objects of another class derived from IBitFlag. For example, using the bitwise OR operator. Macro Descriptions You can use the following macros to declare classes derived from IBitFlag: INESTEDBITFLAGCLASSDEF0 macro Declares a logical base bitwise flag class scoped to another class. A logical base bitwise class is a class of bitwise flag objects that cannot be constructed from a bitwise flag object of another class. INESTEDBITFLAGCLASSDEF1 macro Declares a bitwise flag class whose objects can be constructed from an object of another bitwise flag class. The library assumes both bitwise flag classes have the same name and are scoped to another class. INESTEDBITFLAGCLASSDEF2 macro Declares a bitwise flag class whose objects can be constructed from an object of two other bitwise flag classes. The library assumes all the bitwise flag classes have the same name and are scoped to another class. INESTEDBITFLAGCLASSDEF3 macro Declares a bitwise flag class whose objects can be constructed from an object of three other bitwise flag classes. The library assumes all the bitwise flag classes have the same name and are scoped to another class. INESTEDBITFLAGCLASSDEF4 macro Declares a bitwise flag class whose objects can be constructed from an object of four other bitwise flag classes. The library assumes all the bitwise flag classes have the same name and are scoped to another class. INESTEDBITFLAGCLASSFUNCS macro Declares global functions that operate on a class of bitwise flag objects scoped to another class. The functions are global, rather than member functions, to allow for commutative operations between objects of different bitwise flag classes. Note: Do not use this macro to define global functions for a logical base style class (one declared with the INESTEDBITFLAGCLASSDEF0 macro). ═══ Public Functions - IBitFlag ═══ Comparisons operator != operator == Queries asExtendedUnsignedLong asUnsignedLong Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IBitFlag - Assignment ═══ Use this member to set the value of the object. ═══ IBitFlag - Comparisons ═══ Use these members to compare bitflag values. ═══ IBitFlag - Constructors ═══ You can only construct objects of this class from an unsigned long value, which represents the styles accepted by the system, and, optionally, an unsigned long value that represents extended styles. Note: This constructor is protected because objects derived from this class should not be arbitrarily constructed. To provide type safety for window and control constructors, you can only specify the following: Existing style objects Existing attribute objects Combinations of these objects ═══ IBitFlag - Queries ═══ Use these members to return the value of the object. ═══ Protected Functions - IBitFlag ═══ Assignment setValue Constructors IBitFlag ═══ Protected Data - IBitFlag ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.7.1. IBitFlag::asExtendedUnsignedLong ═══ Converts the upper 32-Bits of the object to an unsigned long value. public: unsigned long asExtendedUnsignedLong() const; ═══ 1.7.2. IBitFlag::asUnsignedLong ═══ Converts the object to an unsigned long value. public: unsigned long asUnsignedLong() const; ═══ 1.7.3. IBitFlag::IBitFlag ═══ You can only construct objects of this class from an unsigned long value, which represents the styles accepted by the system, and, optionally, an unsigned long value that represents extended styles. Note: This constructor is protected because objects derived from this class should not be arbitrarily constructed. To provide type safety for window and control constructors, you can only specify the following: Existing style objects Existing attribute objects Combinations of these objects protected: IBitFlag( unsigned long value, unsigned long extendedValue = 0); ═══ 1.7.4. IBitFlag::operator != ═══ Used to compare two bitflag values for inequality. public: Boolean operator !=(const IBitFlag& rhs) const; ═══ 1.7.5. IBitFlag::operator == ═══ Used to compare two bitflag values for equality. public: Boolean operator ==(const IBitFlag& rhs) const; ═══ 1.7.6. IBitFlag::setValue ═══ You can use this function to assign an unsigned long value for the system styles to the object, and optionally an unsigned long value that represents extended styles. protected: IBitFlag& setValue( unsigned long value, unsigned long extendedValue = 0); ═══ 1.8. IBuffer ═══ Description Derivation Public Functions Protected Functions Public Data Protected Data Nested Types Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IBuffer ═══ IBase │ IVBase │ IBuffer Inherited by: IDBCSBuffer ═══ Class Description - IBuffer ═══ ibuffer.hpp Objects of the IBuffer class define the contents of an IString. ═══ Public Functions - IBuffer ═══ Comparisons compare Diagnostics asDebugInfo Editing center change copy insert leftJustify lowerCase overlayWith remove reverse rightJustify strip translate upperCase NLS Testing includesDBCS includesMBCS includesSBCS isDBCS isMBCS isSBCS isValidDBCS isValidMBCS Queries charType contents defaultBuffer fromContents length next null useCount Reallocation checkAddition checkMultiplication newBuffer overflow setDefaultBuffer Reference Counting addRef removeRef Searches indexOf indexOfAnyBut indexOfAnyOf lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf Subset subString Testing isAlphabetic isAlphanumeric isASCII isControl isDigits isGraphics isHexDigits isLowerCase isPrintable isPunctuation isUpperCase isWhiteSpace Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IBuffer - Allocation ═══ Use these protected members to allocate and deallocate IBuffer objects. ═══ IBuffer - Comparisons ═══ Use these members to compare the IBuffer's contents to some other character array. ═══ IBuffer - Constructors ═══ Constructors for this class require the length of the buffer, which is the value to be stored in the len data member. ═══ IBuffer - DBCS Table ═══ Use this character array member to test characters for DBCS validity. ═══ IBuffer - Diagnostics ═══ Use these members to provide diagnostic information about the buffer. ═══ IBuffer - Editing ═══ These members are called by the corresponding IString members to edit the buffer's contents. ═══ IBuffer - Implementation ═══ This member helps implement this class. ═══ IBuffer - NLS Testing ═══ Corresponding IString members use these members to test the buffer's contents. These tests are character-set-specific. ═══ IBuffer - Protected Queries ═══ This member helps implement this class. ═══ IBuffer - Queries ═══ Use these members to access various attributes of a buffer. ═══ IBuffer - Reallocation ═══ Use these members to manage reallocation of IBuffers when strings' contents are modified. ═══ IBuffer - Reference Counting ═══ Use these members to manage the buffer reference count. ═══ IBuffer - Search Initialization ═══ These members help implement this class. ═══ IBuffer - Searches ═══ These members are called by the corresponding IString members to search the buffer's contents. ═══ IBuffer - Subset ═══ Use this member when a subset of characters is required. ═══ IBuffer - Testing ═══ Corresponding IString members use these members to test the buffer's contents. ═══ Protected Functions - IBuffer ═══ Allocation allocate operator delete operator new Constructors IBuffer ~IBuffer Implementation initialize Protected Queries className Search Initialization startBackwardsSearch startSearch ═══ Public Data - IBuffer ═══ DBCS Table dbcsTable ═══ Protected Data - IBuffer ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.8.1. IBuffer::addRef ═══ Increments the usage count. public: void addRef(); ═══ 1.8.2. IBuffer::allocate ═══ Returns a new buffer of the specified length. protected: virtual IBuffer* allocate(unsigned bufLength) const; ═══ 1.8.3. IBuffer::asDebugInfo ═══ Returns information about the buffer's internal representation that you can use for debugging. public: virtual IString asDebugInfo() const; ═══ 1.8.4. IBuffer::center ═══ Centers the receiver within a string of the specified length. public: virtual IBuffer* center(unsigned newLen, char padCharacter); ═══ 1.8.5. IBuffer::change ═══ Changes occurrences of a specified pattern to a specified replacement string. You can specify the number of changes to perform. The default is to change all occurrences of the pattern. You can also specify the position in the receiver at which to begin. The parameters are the following: pSource The pattern string as NULL-terminated string. The library searches for the pattern string within the receiver's data. sourceLen The length of the source string. pTarget The target string as a NULL-terminated string. It replaces the occurrences of the pattern string in the receiver's data. targetLen The length of the target string. startPos The position to start the search at within the target's data. numChanges The number of patterns to search for and change. public: virtual IBuffer* change( const char* pSource, unsigned sourceLen, const char* pTarget, unsigned targetLen, unsigned startPos, unsigned numChanges); ═══ 1.8.6. IBuffer::charType ═══ Returns the type of a character at the specified index. public: virtual IStringEnum::CharType charType( unsigned index) const; ═══ 1.8.7. IBuffer::checkAddition ═══ Verifies that the two parameters, when added, do not overflow an unsigned integer. public: static unsigned checkAddition( unsigned addend1, unsigned addend2); ═══ 1.8.8. IBuffer::checkMultiplication ═══ Verifies that the two parameters, when multiplied, do not overflow an unsigned integer. public: static unsigned checkMultiplication( unsigned factor1, unsigned factor2); ═══ 1.8.9. IBuffer::className ═══ Returns the name of the class (IBuffer). protected: virtual const char* className() const; ═══ 1.8.10. IBuffer::compare ═══ Compares the buffer's contents to the contents of the specified character array. public: virtual Comparison compare( const void* p, unsigned len) const; ═══ 1.8.11. IBuffer::contents ═══ Returns the address of the buffer's contents. Overload 1 public: const char* contents() const; Overload 2 public: char* contents(); ═══ 1.8.12. IBuffer::copy ═══ Replaces the receiver's contents with a specified number of replications of itself. public: virtual IBuffer* copy(unsigned numCopies); ═══ 1.8.13. IBuffer::dbcsTable ═══ Table of DBCS first-byte flags ('dbcsTable[n] == 1' if and only if n is a valid DBCS first byte). public: static char dbcsTable [ 256 ]; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.8.14. IBuffer::defaultBuffer ═══ Returns the address of the NULL buffer for the class. This is a static function. public: static IBuffer* defaultBuffer(); ═══ 1.8.15. IBuffer::fromContents ═══ Returns the address of IBuffer using the specified pointer to its contents. This is a static function. Note: It is important that pBuffer point to the actual beginning of data from an IBuffer object. The User Interface Class Library can return only values from the contents function of this class. Otherwise, if the returned IBuffer pointer is used, errors could occur. public: static IBuffer* fromContents(const char* pBuffer); ═══ 1.8.16. IBuffer::IBuffer ═══ Constructors for this class require the length of the buffer, which is the value to be stored in the len data member. protected: IBuffer(unsigned newLen); Initializes the reference count and null terminates the buffer. ═══ 1.8.17. IBuffer::includesDBCS ═══ If any characters are DBCS (double-byte character set), true is returned. public: virtual Boolean includesDBCS() const; ═══ 1.8.18. IBuffer::includesMBCS ═══ If any characters are MBCS (multiple-byte character set), true is returned. public: virtual Boolean includesMBCS() const; ═══ 1.8.19. IBuffer::includesSBCS ═══ If any characters are SBCS (single-byte character set), true is returned. public: virtual Boolean includesSBCS() const; ═══ 1.8.20. IBuffer::indexOf ═══ Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, 0 is returned. In addition to IStrings, you can also specify a single character or an IStringTest. Overload 1 public: virtual unsigned indexOf( const IStringTest& aTest, unsigned startPos = 1) const; Overload 2 public: virtual unsigned indexOf( const char* pString, unsigned len, unsigned startPos = 1) const; ═══ 1.8.21. IBuffer::indexOfAnyBut ═══ Returns the index of the first character of the receiver that is not in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that fails the test prescribed by a specified IStringTestobject. Overload 1 public: virtual unsigned indexOfAnyBut( const IStringTest& aTest, unsigned startPos = 1) const; Overload 2 public: virtual unsigned indexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 1) const; ═══ 1.8.22. IBuffer::indexOfAnyOf ═══ Returns the index of the first character of the receiver that is a character in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that passes the test prescribed by a specified IStringTestobject. Overload 1 public: virtual unsigned indexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 1) const; Overload 2 public: virtual unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 1) const; ═══ 1.8.23. IBuffer::initialize ═══ Initializes (sets up a NULL buffer, a DBCS table, and so forth). This is a static function. protected: static IBuffer* initialize(); ═══ 1.8.24. IBuffer::insert ═══ Inserts the specified string after the specified location. public: virtual IBuffer* insert( const char* pInsert, unsigned insertLen, unsigned pos, char padCharacter); ═══ 1.8.25. IBuffer::isAlphabetic ═══ If all the characters are in {'A'-'Z','a'-'z'}, true is returned. public: virtual Boolean isAlphabetic() const; ═══ 1.8.26. IBuffer::isAlphanumeric ═══ If all the characters are in {'A'-'Z','a'-'z','0'-'9'}, true is returned. public: virtual Boolean isAlphanumeric() const; ═══ 1.8.27. IBuffer::isASCII ═══ If all the characters are in {0x00-0x7F}, true is returned. public: virtual Boolean isASCII() const; ═══ 1.8.28. IBuffer::isControl ═══ Returns true if all the characters are control characters. Control characters are defined by the iscntrl() C Library function as defined in the cntrl locale source file and in the cntrl class of the LC_CTYPE category of the current locale. For example, on ASCII operating systems, control characters are those in the range {0x00-0x1F,0x7F}. public: virtual Boolean isControl() const; ═══ 1.8.29. IBuffer::isDBCS ═══ If all the characters are DBCS, true is returned. public: virtual Boolean isDBCS() const; ═══ 1.8.30. IBuffer::isDigits ═══ If all the characters are in {'0'-'9'}, true is returned. public: virtual Boolean isDigits() const; ═══ 1.8.31. IBuffer::isGraphics ═══ Returns true if all the characters are graphics characters. Graphics characters are printable characters excluding the space character, as defined by the isgraph() C Library function in the graph locale source file and in the graph class of the LC_CTYPE category of the current locale. For example, on ASCII operating systems, graphics characters are those in the range {0x21-0x7E}. public: virtual Boolean isGraphics() const; ═══ 1.8.32. IBuffer::isHexDigits ═══ If all the characters are in {'0'-'9','A'-'F','a'-'f'}, true is returned. public: virtual Boolean isHexDigits() const; ═══ 1.8.33. IBuffer::isLowerCase ═══ If all the characters are in {'a'-'z'}, true is returned. public: virtual Boolean isLowerCase() const; ═══ 1.8.34. IBuffer::isMBCS ═══ If all the characters are MBCS, true is returned. public: virtual Boolean isMBCS() const; ═══ 1.8.35. IBuffer::isPrintable ═══ Returns true if all the characters are printable characters. Printable characters are defined by the isprint() C Library function as defined in the print locale source file and in the print class of the LC_CTYPE category of the current locale. For example, on ASCII systems, printable characters are those in the range {0x20-0x7E}. public: virtual Boolean isPrintable() const; ═══ 1.8.36. IBuffer::isPunctuation ═══ If none of the characters is white space, a control character, or an alphanumeric character, true is returned. public: virtual Boolean isPunctuation() const; ═══ 1.8.37. IBuffer::isSBCS ═══ If all the characters are SBCS, true is returned. public: virtual Boolean isSBCS() const; ═══ 1.8.38. IBuffer::isUpperCase ═══ If all the characters are in {'A'-'Z'}, true is returned. public: virtual Boolean isUpperCase() const; ═══ 1.8.39. IBuffer::isValidDBCS ═══ If no DBCS characters have a 0 second byte, true is returned. public: virtual Boolean isValidDBCS() const; ═══ 1.8.40. IBuffer::isValidMBCS ═══ If no MBCS characters have a 0 second byte, true is returned. public: virtual Boolean isValidMBCS() const; ═══ 1.8.41. IBuffer::isWhiteSpace ═══ Returns true if all the characters are whitespace characters. Whitespace characters are defined by the isspace() C Library function as defined in the space locale source file and in the space class of the LC_CTYPE category of the current locale. For example, on ASCII systems, printable characters are those in the range {0x09-0x0D,0x20}. public: virtual Boolean isWhiteSpace() const; ═══ 1.8.42. IBuffer::lastIndexOf ═══ Returns the index of the last occurrence of the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The returned value is in the range 0 <= x <= startPos. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: virtual unsigned lastIndexOf( const char* pString, unsigned len, unsigned startPos = 0) const; Overload 2 public: virtual unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.8.43. IBuffer::lastIndexOfAnyBut ═══ Returns the index of the last character not in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: virtual unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned startPos = 0) const; Overload 2 public: virtual unsigned lastIndexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 0) const; ═══ 1.8.44. IBuffer::lastIndexOfAnyOf ═══ Returns the index of the last character in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: virtual unsigned lastIndexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 0) const; Overload 2 public: virtual unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.8.45. IBuffer::leftJustify ═══ Left-justifies the receiver in a string of the specified length. If the new length (newLen) is larger than the current length, the string is extended by the pad character (padCharacter). The default pad character is a blank. public: virtual IBuffer* leftJustify( unsigned newLen, char padCharacter); ═══ 1.8.46. IBuffer::length ═══ Returns the length of the buffer's contents. public: unsigned length() const; ═══ 1.8.47. IBuffer::lowerCase ═══ Translates all upper-case letters in the receiver to lower-case. public: virtual IBuffer* lowerCase(); ═══ 1.8.48. IBuffer::newBuffer ═══ Allocates a new buffer and initializes it with the contents of up to three specified buffers. The parameters are the following: p1 The pointer to the first part to be copied into the data area of the new buffer. The first part is len1 bytes long. If the pointer is NULL, the padChar is copied for len1 bytes. len1 The length, in bytes, of the first part to be copied into the new buffer. p2 A pointer to the second part, immediately following the first part, to be copied into the data area of the new buffer. The second part is len2 bytes long. If the pointer is NULL, the padChar is copied for len2 bytes. If nothing is specified for p2, it is NULL. len2 The length, in bytes, of the second part to be copied into the new buffer. If nothing is specified for len2, it defaults to 0 bytes. p3 The pointer to the third part, immediately following the second part, to be copied into the data area of the new buffer. The third part is len3 bytes long. If the pointer is NULL, the padChar is copied for len3 bytes. If nothing is specified for p3, it is NULL. len3 The length, in bytes, of the third part to be copied into the new buffer. If nothing is specified for len3, it defaults to 0 bytes. padChar The character to use as the pad in the cases of p1, p2, or p3 being NULL. If you do not specify a padChar, it defaults to the character 0. Note: If the sum of len1, len2, and len3 is 0, a reference to the NULL buffer for this class is added and the address is returned. public: IBuffer* newBuffer( const void* p1, unsigned len1, const void* p2 = 0, unsigned len2 = 0, const void* p3 = 0, unsigned len3 = 0, char padChar = 0) const; ═══ 1.8.49. IBuffer::next ═══ Returns a pointer to the next character, not the next byte, in the buffer. Overload 1 public: virtual const char* next(const char* prev) const; Overload 2 public: virtual char* next(const char* prev); ═══ 1.8.50. IBuffer::null ═══ Returns the address of the NULL buffer. public: IBuffer* null() const; ═══ 1.8.51. IBuffer::operator delete ═══ Deallocates a buffer. Overload 1 protected: void operator delete(void* p); Overload 2 protected: void operator delete( void* p, const char* filename, size_t linenum); ═══ 1.8.52. IBuffer::operator new ═══ Allocates space for a buffer of the specified length. The returned pointer is an area the size of an IBuffer large enough to hold data of size bufLen. Overload 1 protected: void* operator new( size_t t, const char* filename, size_t linenum, unsigned bufLen); Overload 2 protected: void* operator new(size_t t, unsigned bufLen); ═══ 1.8.53. IBuffer::overflow ═══ Throws an exception when IBuffer::checkAdditionor IBuffer::checkMultiplication detect an overflow. public: static unsigned overflow(); Exceptions ┌────────────────────┬────────────────────────────────────────┐ │IInvalidRequest │You made an IBuffer request causing an │ │ │overflow. Typically, this occurs during │ │ │object construction or during an │ │ │operation which grows an underlying │ │ │IBuffer object. Likely culprits might be│ │ │an IBuffer::newBuffer or IString::change│ │ │call. │ └────────────────────┴────────────────────────────────────────┘ ═══ 1.8.54. IBuffer::overlayWith ═══ Replaces a specified portion of the receiver's contents with the specified string. If pos is beyond the end of the receiver's data, it is padded with the pad character (padCharacter). public: virtual IBuffer* overlayWith( const char* overlay, unsigned len, unsigned pos, char padCharacter); ═══ 1.8.55. IBuffer::remove ═══ Deletes the specified portion of the string (that is, the substring) from the receiver. You can use this function to truncate an IString object at a specific position. For example: aString.remove(8); removes the substring beginning at index 8 and takes the rest of the string as a default. public: virtual IBuffer* remove( unsigned startPos, unsigned numChars); ═══ 1.8.56. IBuffer::removeRef ═══ Decrements the usage count and deletes the buffer when the usage count goes to 0. public: void removeRef(); ═══ 1.8.57. IBuffer::reverse ═══ Reverses the receiver's contents. public: virtual IBuffer* reverse(); ═══ 1.8.58. IBuffer::rightJustify ═══ Right-justifies the receiver in a string of the specified length. If the receiver's data is shorter than the requested length (newLen), it is padded on the left with the pad character (padCharacter). The default pad character is a blank. public: virtual IBuffer* rightJustify( unsigned newLen, char padCharacter); ═══ 1.8.59. IBuffer::setDefaultBuffer ═══ Sets the default (NULL) buffer. The specified buffer must be comprised of a single NULL byte. public: static void setDefaultBuffer(IBuffer* newDefaultBuffer); ═══ 1.8.60. IBuffer::startBackwardsSearch ═══ Initializes a search of type IString::lastIndexOf. If searchLen is greater than the length of the buffer, 0 is returned indicating an invalid search request. If the starting position is 0 or beyond the last searchLen bytes of the buffer, the position where the last searchLen bytes start in the buffer is returned. If the starting position is 1 through the last searchLen bytes, the value of startingPos is returned. protected: virtual unsigned startBackwardsSearch( unsigned startPos, unsigned searchLen) const; ═══ 1.8.61. IBuffer::startSearch ═══ Initializes a search of type IString::indexOf. If startPos is 0, the search uses a starting position of 1. If the specified startPos and searchLen result in an invalid search, 0 is returned. This usually occurs when the sum of startPos and searchLen is greater than the size of the buffer. protected: virtual unsigned startSearch( unsigned startPos, unsigned searchLen) const; ═══ 1.8.62. IBuffer::strip ═══ Strips both leading and trailing character or characters. You can specify the character or characters as the following: A char* array An IStringTestobject The default is white space. Overload 1 public: virtual IBuffer* strip( const IStringTest& aTest, IStringEnum::StripMode mode); Overload 2 public: virtual IBuffer* strip( const char* pChars, unsigned len, IStringEnum::StripMode mode); ═══ 1.8.63. IBuffer::subString ═══ Returns a new IBuffer, of the same type as the previous one, containing the specified subset of characters. The parameters are the following: startPos The index at which to start the substring. If startPos is 0, the function uses position 1. If startPos is beyond the end of the buffer, nothing is copied. The buffer is filled out by the specified padding character. len The length to copy from the buffer. If the length extends beyond the end of the buffer, only the portion up to the end is copied. The buffer is then padded. If len is 0, a reference to the NULL buffer is returned. padCharacter Specifies the character the function uses to pad the copied string if less than len bytes have been copied from the source buffer. public: virtual IBuffer* subString( unsigned startPos, unsigned len, char padCharacter) const; ═══ 1.8.64. IBuffer::translate ═══ Converts all of the receiver's characters that are in the first specified string to the corresponding character in the second specified string. public: virtual IBuffer* translate( const char* pInputChars, unsigned inputLen, const char* pOutputChars, unsigned outputLen, char padCharacter); ═══ 1.8.65. IBuffer::upperCase ═══ Translates all lower-case letters in the receiver to upper-case. public: virtual IBuffer* upperCase(); ═══ 1.8.66. IBuffer::useCount ═══ Returns the number of IStrings referring to the buffer. public: unsigned useCount() const; ═══ 1.8.67. IBuffer::~IBuffer ═══ protected: ~IBuffer(); Destructor, does nothing. ═══ Nested Types - IBuffer ═══ Type Definitions Comparison ═══ Type Definition - IBuffer::Comparison ═══ typedef enum { equal , greaterThan , lessThan } Comparison; These enumerators specify the possible valid return codes from IBuffer::compare. equal The buffer's contents are equal to the contents of the specified character array. greaterThan The buffer's contents are greater than the contents of the specified character array. lessThan The buffer's contents are less than the contents of the specified character array. ═══ 1.9. ICLibErrorInfo ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - ICLibErrorInfo ═══ IBase │ IVBase │ IErrorInfo │ ICLibErrorInfo Inherited by none. ═══ Class Description - ICLibErrorInfo ═══ iexcept.hpp Objects of the ICLibErrorInfo class represent error information. When a C library call results in an error condition, objects of the ICLibErrorInfo class are created. The per thread global variable errno is used to obtain the error text. The User Interface Class Library provides the ITHROWCLIBERROR macro for throwing exceptions constructed with ICLibErrorInfo information. This macro has the following parameters: location The name of the C function returning the error code, the name of the file the function is in, and the function's line number. name Use the enumeration IErrorInfo::ExceptionType to specify the type of the exception. The default is accessError. severity Use the enumeration IException::Severity to specify the severity of the error. The default is recoverable. This macro generates code that calls throwCLibError, which does the following: 1. Creates an ICLibErrorInfo object 2. Uses the object to create an IException object 3. Adds the CLibrary error group to the object 4. Adds location information 5. Logs the exception data 6. Throws the exception ═══ Public Functions - ICLibErrorInfo ═══ Constructors ICLibErrorInfo ~ICLibErrorInfo Error Information errorId isAvailable operator const char * text Throw Support throwCLibError Inherited Members IErrorInfo errorId isAvailable operator const char * text throwError IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ ICLibErrorInfo - Constructors ═══ You can construct and destruct objects of this class. You cannot copy or assign objects of this class. ═══ ICLibErrorInfo - Error Information ═══ Use these members to return the error information provided by objects of this class. ═══ ICLibErrorInfo - Hidden Functions ═══ These members are hidden to prevent you from copying and assigning objects of this class. ═══ ICLibErrorInfo - Throw Support ═══ Use these members to support the throwing of exceptions. ═══ Protected Data - ICLibErrorInfo ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.9.1. ICLibErrorInfo::errorId ═══ Returns the value of errno, which you can use to obtain the errno information. public: virtual unsigned long errorId() const; ═══ 1.9.2. ICLibErrorInfo::ICLibErrorInfo ═══ You can construct and destruct objects of this class. You cannot copy or assign objects of this class. public: ICLibErrorInfo(const char* CLibFunctionName = 0); You can only construct objects of this class using the default constructor. Note: If the constructor cannot load the error text, the User Interface Class Library provides the following default text: "No error text is available." CLibFunctionName (Optional) The name of the failing C library function. If you specify CLibFunctionName, the constructor prefixes it to the error text. ═══ 1.9.3. ICLibErrorInfo::isAvailable ═══ If the error text is available, true is returned. public: virtual Boolean isAvailable() const; ═══ 1.9.4. ICLibErrorInfo::operator const char * ═══ Returns the error text. public: virtual operator const char *() const; ═══ 1.9.5. ICLibErrorInfo::text ═══ Returns the error text. public: virtual const char* text() const; ═══ 1.9.6. ICLibErrorInfo::throwCLibError ═══ Creates an ICLibErrorInfo object and uses the text from it to the following: 1. Create an exception object 2. Add the location information to it 3. Log the exception data 4. Throw the exception functionName The name of the function where the exception occurred. location An IExceptionLocation object containing the following: Function name File name Line number where the function is called name Use the enumeration IErrorInfo::ExceptionType to specify the type of the exception. The default is accessError. severity Use the enumeration IException::Severity to specify the severity of the error. The default is recoverable. public: static void throwCLibError( const char* functionName, const IExceptionLocation& location, IErrorInfo::ExceptionType name = accessError, IException::Severity severity = recoverable); ═══ 1.9.7. ICLibErrorInfo::~ICLibErrorInfo ═══ public: virtual ~ICLibErrorInfo(); ═══ 1.10. IDate ═══ Description Derivation Constructors Public Functions Protected Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IDate ═══ IBase │ IDate Inherited by none. ═══ Class Description - IDate ═══ idate.hpp Objects of the IDate class represent specified dates. This class also provides general day and date-handling functions. Externally, dates consist of three pieces of information: A year A month within that year A day within that month The User Interface Class Library also lets you specify the day within the year. The IDate class returns language-sensitive information, such as names of days and months, in the language defined by the user's system. See the description of the standard C function setlocale in the VisualAge C++: C Library Reference for information about setting the locale. ═══ Public Functions - IDate ═══ Comparisons operator != operator < operator <= operator == operator > operator >= Constructors IDate Conversions asCDATE julianDate Current Date today Day Queries dayName dayOfMonth dayOfWeek dayOfYear Diagnostics asString General Date Queries dayName daysInMonth daysInYear monthName Manipulation operator + operator += operator - operator -= Month Queries monthName monthOfYear Validation isLeapYear isValid Year Queries year Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IDate - Comparisons ═══ Use these members to compare two IDates. Use any of the full complement of comparison operators and applying the natural meaning. ═══ IDate - Constructors ═══ You can construct objects of this class in the following ways: Use the default constructor, which returns the current day. Give the year, month, and day for the desired day. These parameters can be in either month/day/year or day/month/year order. Give the year and day of the year for the desired day. Use IDate::today to return the current date. Copy another IDate object. Give the Julian day number, as a long. Give a container details CDATE structure. ═══ IDate - Conversions ═══ Use these members to retrieve other representations of the date. ═══ IDate - Current Date ═══ Use this member when you need the current date. ═══ IDate - Day Queries ═══ Use these members to access the day portion of an IDate object. ═══ IDate - Day, Month, and Year Types ═══ IDate defines the following related types (enumerations): DayOfWeek Month YearFormat IDate member function use these enumerations to simplify the passing of day, month and year format data. ═══ IDate - Diagnostics ═══ These members provide an IString representation for an IDate object and the capability to output the object to a stream. The formats include both mm-dd-yy and strftime conversion specifications. Often, you use these members to write trace information when debugging. ═══ IDate - General Date Queries ═══ These members are static. They provide general IDate utilities independent of specific IDates. Typically, you use them to determine calendar information or to convert IDate enumeration data to string values. ═══ IDate - Implementation ═══ These members initializes an IDate object. ═══ IDate - Manipulation ═══ Use these members to update an IDate object using addition or subtraction of another IDate object. Use any of the full complement of addition or subtraction operators and apply the natural meaning. ═══ IDate - Month Queries ═══ Use these members to access the month portion of an IDate object. ═══ IDate - Validation ═══ Use these static members to validate the passed-date data. They test the validity of a given day and provide a leap year test for a given year. ═══ IDate - Year Queries ═══ Use this member to access the year portion of an IDate object. ═══ Protected Functions - IDate ═══ Implementation initialize ═══ Protected Data - IDate ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.10.1. IDate::asCDATE ═══ Returns a container CDATE structure for the date. public: _CDATE asCDATE() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.10.2. IDate::asString ═══ Returns the IDate as a string. The default is formatted per the system (mm-dd-yy). The alternate version of asString lets you use any strftime conversion specifiers. For example, "%x" yields a string such as "Apr 10 1959". There are two implementations of asString. The parameters are the following: yearFmt Specifies how the system will display the year. If you do not specify the format, the default is yy. Use the enumeration IDate::YearFormat for valid yearFmt values. fmt Specifies the conversion specifier, which is a character string you can use to describe how to output the date. Use the date specifiers that are valid in the C function strftime. The conversion specifiers that apply to IDate and their meanings are listed in the following table. ITime::asString provides the conversion specifiers that apply to ITime. For more information about the strftime function, refer to the VisualAge C++: C Library Reference. Specifier Meaning ─────────────────────────────────────────────────── %a Insert abbreviated weekday name of locale. ─────────────────────────────────────────────────── %A Insert full weekday name of locale. ─────────────────────────────────────────────────── %b Insert abbreviated month name of locale. ─────────────────────────────────────────────────── %B Insert full month name of locale. ─────────────────────────────────────────────────── %c Insert date and time of locale. ─────────────────────────────────────────────────── %d Insert day of the month (01-31). ─────────────────────────────────────────────────── %j Insert day of the year (001-366). ─────────────────────────────────────────────────── %m Insert month (01-12). ─────────────────────────────────────────────────── %U Insert week number of the year (00-53) where Sunday is the first day of the week. ─────────────────────────────────────────────────── %w Insert weekday (0-6) where Sunday is 0. ─────────────────────────────────────────────────── %W Insert week number of the year (00-53) where Monday is the first day of the week. ─────────────────────────────────────────────────── %x Insert date representation of locale. ─────────────────────────────────────────────────── %y Insert year without the century (00-99). ─────────────────────────────────────────────────── %Y Insert year. For example, if you want to return the month, day, and year (without the century), construct an IDate object, and then call asString as follows: asString("%m:%d:%y") Overload 1 public: IString asString(YearFormat yearFmt = yy) const; Used in samples: Hello World Sample - Version 6: ahellow6.cpp Lancelot - A Valiant Example: ltimec.cpp Overload 2 public: IString asString(const char* fmt) const; ═══ 1.10.3. IDate::dayName ═══ Returns the name of the receiver's day of the week: The first version of dayName accepts a specified day. It returns the name of the day of the week that is equivalent to the index value in aDay. The second version of dayName accepts no parameters. It returns the name of the receiver's day of the week, such as "Monday". Overload 1 public: static IString dayName(DayOfWeek aDay); Overload 2 public: IString dayName() const; ═══ 1.10.4. IDate::dayOfMonth ═══ Returns the day in the receiver's month as an integer from 1 to 31. public: int dayOfMonth() const; Used in sample: Hello World Sample - Version 6: ahellow6.cpp ═══ 1.10.5. IDate::dayOfWeek ═══ Returns the index of the receiver's day of the week: Monday through Sunday. public: DayOfWeek dayOfWeek() const; Used in sample: Lancelot - A Valiant Example: ltimec.cpp ═══ 1.10.6. IDate::dayOfYear ═══ Returns the day in the receiver's year as an integer from 1 to 366. public: int dayOfYear() const; ═══ 1.10.7. IDate::daysInMonth ═══ Returns the number of days in a specified month of a specified year. You must specify aYear in yyyy format. public: static int daysInMonth(Month aMonth, int aYear); ═══ 1.10.8. IDate::daysInYear ═══ Returns the number of days in a specified year. You must specify aYear in yyyy format. public: static int daysInYear(int aYear); ═══ 1.10.9. IDate::IDate ═══ You can construct objects of this class in the following ways: Use the default constructor, which returns the current day. Give the year, month, and day for the desired day. These parameters can be in either month/day/year or day/month/year order. Give the year and day of the year for the desired day. Use IDate::today to return the current date. Copy another IDate object. Give the Julian day number, as a long. Give a container details CDATE structure. Overload 1 public: IDate(int aYear, int aDay); This constructor constructs an IDate from the year and day of the year. The day of year is the number of days starting at January 1. Overload 2 public: IDate(); Using this constructor returns the current day; it's the default. Used in samples: Hello World Sample - Version 6: ahellow6.cpp Lancelot - A Valiant Example: ltimec.cpp Overload 3 public: IDate(Month aMonth, int aDay, int aYear); You use this constructor when passing parameters in month/day/year order. Overload 4 public: IDate(int aDay, Month aMonth, int aYear); You use this constructor when passing parameters in day/month/year order. Overload 5 public: IDate(const IDate& aDate); This constructor constructs an IDate by copying another IDate object. Overload 6 public: IDate(unsigned long julianDayNumber); Use this constructor to construct an IDate from a Julian day number, as a long. Overload 7 public: IDate(const _CDATE& cDate); You use this constructor to construct an IDate from a container details CDATE structure. Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.10.10. IDate::initialize ═══ Calculates the Julian day number. The form of the parameters are the following: aMonth mm aDay dd aYear yyyy This function returns a reference to the receiver, initialized to the specified date. protected: IDate& initialize(Month aMonth, int aDay, int aYear); ═══ 1.10.11. IDate::isLeapYear ═══ If the specified year is a leap year, true is returned. Otherwise, false is returned. You must specify aYear in yyyy format. public: static Boolean isLeapYear(int aYear); ═══ 1.10.12. IDate::isValid ═══ Indicates whether the specified date is valid. You must specify aYear in yyyy format. You can specify the date as: month/day/year day/month/year year/day For example, February 29, 1990 is not a valid date because February only had 28 days in 1990. Overload 1 public: static Boolean isValid(Month aMonth, int aDay, int aYear); Overload 2 public: static Boolean isValid(int aDay, Month aMonth, int aYear); Overload 3 public: static Boolean isValid(int aYear, int aDay); ═══ 1.10.13. IDate::julianDate ═══ Returns the Julian day number of the receiver IDate. This function uses the true definition of a Julian date, which means it returns the number of days from January 1, 4713 B.C. public: unsigned long julianDate() const; ═══ 1.10.14. IDate::monthName ═══ Returns the name of the receiver's month: The first version of this function accepts no parameters. It returns the name of the receiver's month, such as "March". The second version of this function accepts a specified month. It returns the name of the month that is equivalent to the index value in aMonth. Overload 1 public: static IString monthName(Month aMonth); Overload 2 public: IString monthName() const; Used in sample: Hello World Sample - Version 6: ahellow6.cpp ═══ 1.10.15. IDate::monthOfYear ═══ Returns the index of the receiver's month of the year: January through December. public: Month monthOfYear() const; ═══ 1.10.16. IDate::operator != ═══ If the IDate objects represent different dates, true is returned. public: Boolean operator !=(const IDate& aDate) const; ═══ 1.10.17. IDate::operator + ═══ Adds an integral number of days to the left-hand operand, yielding a new IDate. public: IDate operator +(int numDays) const; ═══ 1.10.18. IDate::operator += ═══ Adds an integral number of days to the left-hand operand, assigning the result to that operand. public: IDate& operator +=(int numDays); Used in sample: Lancelot - A Valiant Example: ltimec.cpp ═══ 1.10.19. IDate::operator - ═══ Subtracts an integral number of days from the left-hand operand, yielding a new IDate. If the right-hand operand is also an IDate, the operator yields the number of days between the dates. The parameters are the following: numDays The function subtracts numDays from the receiver's value and returns an IDate object. aDate The function returns the difference in the number of days between the receiver and aDate. If the receiver is greater than aDate, the difference is positive. Overload 1 public: IDate operator -(int numDays) const; Overload 2 public: long operator -(const IDate& aDate) const; ═══ 1.10.20. IDate::operator -= ═══ Subtracts an integral number of days from the right-hand operand, assigning the result to that operand. public: IDate& operator -=(int numDays); Used in sample: Lancelot - A Valiant Example: ltimec.cpp ═══ 1.10.21. IDate::operator < ═══ If the left-hand operand represents a date prior to the date represented by the right-hand operand, true is returned. public: Boolean operator <(const IDate& aDate) const; ═══ 1.10.22. IDate::operator <= ═══ If the left-hand operand represents a date prior to or identical to the date represented by the right-hand operand, true is returned. public: Boolean operator <=(const IDate& aDate) const; ═══ 1.10.23. IDate::operator == ═══ If the IDate objects represent the same date, true is returned. public: Boolean operator ==(const IDate& aDate) const; ═══ 1.10.24. IDate::operator > ═══ If the left-hand operand represents a date subsequent to the date represented by the right-hand operand, true is returned. public: Boolean operator >(const IDate& aDate) const; ═══ 1.10.25. IDate::operator >= ═══ If the left-hand operand represents a date subsequent to or identical to the date represented by the right-hand operand, true is returned. public: Boolean operator >=(const IDate& aDate) const; ═══ 1.10.26. IDate::today ═══ Returns the current date. This static function can be used as an IDate constructor. public: static IDate today(); ═══ 1.10.27. IDate::year ═══ Returns the receiver's year. The returned value is in the yyyy format. public: int year() const; Used in sample: Hello World Sample - Version 6: ahellow6.cpp ═══ Nested Types - IDate ═══ Type Definitions Month DayOfWeek YearFormat ═══ Type Definition - IDate::Month ═══ typedef enum { January = 1 , February , March , April , May , June , July , August , September , October , November , December } Month; A typedef that provides the values January through December for the months of the year. ═══ Type Definition - IDate::DayOfWeek ═══ typedef enum { Monday = 0 , Tuesday , Wednesday , Thursday , Friday , Saturday , Sunday } DayOfWeek; A typedef that provides the values Monday through Sunday for the days of the week. ═══ Type Definition - IDate::YearFormat ═══ typedef enum { yy , yyyy } YearFormat; A typedef that specifies the number of digits in the year for the default asString format (yy or yyyy). ═══ 1.11. IDBCSBuffer ═══ Description Derivation Public Functions Protected Functions Public Data Protected Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IDBCSBuffer ═══ IBase │ IVBase │ IBuffer │ IDBCSBuffer Inherited by none. ═══ Class Description - IDBCSBuffer ═══ idbcsbuf.hpp Objects of the IDBCSBuffer class implement the version of IString contents that supports mixed double-byte character set (DBCS) characters. This class also supports UNIX multiple-byte character set (MBCS) characters. This class ensures that multiple-byte characters are processed properly. The use of this class is transparent to the user of class IString. ═══ Public Functions - IDBCSBuffer ═══ Allocation allocate Editing center insert leftJustify lowerCase overlayWith remove reverse rightJustify strip translate upperCase NLS Testing includesDBCS includesMBCS includesSBCS isDBCS isMBCS isSBCS isValidDBCS isValidMBCS Queries charType next Searches indexOf indexOfAnyBut indexOfAnyOf lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf Subset subString Inherited Members IBuffer addRef asDebugInfo center change charType checkAddition checkMultiplication compare contents copy defaultBuffer fromContents includesDBCS includesMBCS includesSBCS indexOf indexOfAnyBut indexOfAnyOf insert isAlphabetic isAlphanumeric isASCII isControl isDBCS isDigits isGraphics isHexDigits isLowerCase isMBCS isPrintable isPunctuation isSBCS isUpperCase isValidDBCS isValidMBCS isWhiteSpace lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf leftJustify length lowerCase newBuffer next null overflow overlayWith remove removeRef reverse rightJustify setDefaultBuffer strip subString translate upperCase useCount IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IDBCSBuffer - Allocation ═══ Use these members to reimplement the allocation members as public. ═══ IDBCSBuffer - Constructors ═══ The constructor for this class is protected. Only IDBCSBuffer::allocate and IBuffer::initialize can call the constructor. ═══ IDBCSBuffer - Editing ═══ Use these members to reimplement the following IString versions of IBuffer members. The following members are called by the corresponding IString members to edit the buffer's contents. ═══ IDBCSBuffer - NLS Testing ═══ Use these members to reimplement the following IString versions of IBuffer members. The corresponding IString members use these members to test the buffer's contents. These tests are character set specific. ═══ IDBCSBuffer - Protected Queries ═══ These members help implement this class. ═══ IDBCSBuffer - Protected Testing ═══ These members help implement this class. ═══ IDBCSBuffer - Queries ═══ Use these members to reimplement the following IString versions of IBuffer members. ═══ IDBCSBuffer - Search Initialization ═══ These members help implement this class. They initialize search data. ═══ IDBCSBuffer - Searches ═══ Use these members to reimplement the following IString versions of IBuffer search members. ═══ IDBCSBuffer - Subset ═══ Use these members to reimplement the following IString versions of IBuffer subsetting members. ═══ Protected Functions - IDBCSBuffer ═══ Constructors IDBCSBuffer ~IDBCSBuffer Protected Queries charLength className maxCharLength prevCharLength Protected Testing isCharValid isDBCS1 isPrevDBCS isSBC Search Initialization startBackwardsSearch startSearch Inherited Members IBuffer allocate className initialize operator delete operator new startBackwardsSearch startSearch ═══ Public Data - IDBCSBuffer ═══ Inherited Members IBuffer dbcsTable ═══ Protected Data - IDBCSBuffer ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.11.1. IDBCSBuffer::allocate ═══ Returns a new buffer of the specified length. public: IBuffer* allocate(unsigned newLen) const; ═══ 1.11.2. IDBCSBuffer::center ═══ Centers the receiver within a string of the specified length. public: IBuffer* center(unsigned newLen, char padCharacter); ═══ 1.11.3. IDBCSBuffer::charLength ═══ Returns the number of bytes in the character beginning at the specified offset. Overload 1 protected: static size_t charLength(char const*); Overload 2 protected: size_t charLength(unsigned pos) const; ═══ 1.11.4. IDBCSBuffer::charType ═══ Returns the type of a character at the specified index. public: IStringEnum::CharType charType(unsigned index) const; ═══ 1.11.5. IDBCSBuffer::className ═══ Returns the name of the class (IDBCSBuffer). protected: const char* className() const; ═══ 1.11.6. IDBCSBuffer::IDBCSBuffer ═══ The constructor for this class is protected. Only IDBCSBuffer::allocate and IBuffer::initialize can call the constructor. protected: IDBCSBuffer(unsigned bufLength); Constructs a buffer of the specified length. The allocated "data" member array actually is 1 byte greater than the argument value (this is achieved automatically via use of the overloaded operator new for class IBuffer). The terminating (extra) byte is set to null. This constructor is protected. IDBCSBufferss must be obtained by using IDBCSBuffer::nullBuffer and subsequent newBuffer calls to existing IDBCSBuffer objects. ═══ 1.11.7. IDBCSBuffer::includesDBCS ═══ If any characters are DBCS (double-byte character set), true is returned. public: Boolean includesDBCS() const; ═══ 1.11.8. IDBCSBuffer::includesMBCS ═══ If any characters are MBCS (multiple-byte character set), true is returned. public: Boolean includesMBCS() const; ═══ 1.11.9. IDBCSBuffer::includesSBCS ═══ If any characters are SBCS (single-byte character set), true is returned. public: Boolean includesSBCS() const; ═══ 1.11.10. IDBCSBuffer::indexOf ═══ Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, 0 is returned. Overload 1 public: unsigned indexOf( const IStringTest& aTest, unsigned startPos = 1) const; Overload 2 public: unsigned indexOf( const char* pString, unsigned len, unsigned startPos = 1) const; ═══ 1.11.11. IDBCSBuffer::indexOfAnyBut ═══ Returns the index of the first character of the receiver that is not in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that fails the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 1) const; Overload 2 public: unsigned indexOfAnyBut( const IStringTest& aTest, unsigned startPos = 1) const; ═══ 1.11.12. IDBCSBuffer::indexOfAnyOf ═══ Returns the index of the first character of the receiver that is a character in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that passes the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 1) const; Overload 2 public: unsigned indexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 1) const; ═══ 1.11.13. IDBCSBuffer::insert ═══ Inserts the specified string after the specified location. public: IBuffer* insert( const char* pInsert, unsigned insertLen, unsigned pos, char padCharacter); ═══ 1.11.14. IDBCSBuffer::isCharValid ═══ If the character at the specified index is in the set of valid characters, true is returned. The parameters are the following: pos The position in the receiver's buffer for the validity check. Warning: It is important that this position not be the second byte of a DBCS character. If it is, you might get false results. pValidChars The string of the valid characters. It can contain a mixture of DBCS and SBCS characters. numValidChars The size of this string of valid characters. protected: Boolean isCharValid( unsigned pos, const char* pValidChars, unsigned numValidChars) const; ═══ 1.11.15. IDBCSBuffer::isDBCS ═══ If all the characters are DBCS, true is returned. public: Boolean isDBCS() const; ═══ 1.11.16. IDBCSBuffer::isDBCS1 ═══ If the byte at the specified offset is the first byte of DBCS, true is returned. Note: The User Interface Class Library provides this function only for compatibility with prior library versions. We recommend using IDBCSBuffer::charLength to determine if the byte is part of a multiple-byte character. protected: Boolean isDBCS1(unsigned pos) const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.11.17. IDBCSBuffer::isMBCS ═══ If all the characters are MBCS, true is returned. public: Boolean isMBCS() const; ═══ 1.11.18. IDBCSBuffer::isPrevDBCS ═══ If the preceding character to the one at the specified offset is a DBCS character, true is returned. Note: The User Interface Class Library provides this function only for compatibility with prior library versions. We recommend using IDBCSBuffer::prevCharLength to determine if the preceding byte is part of a multiple-byte character. protected: Boolean isPrevDBCS(unsigned pos) const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.11.19. IDBCSBuffer::isSBC ═══ If the byte pointed to by the specified character is a single-byte character, true is returned. This is a static function. protected: static Boolean isSBC(char const*); ═══ 1.11.20. IDBCSBuffer::isSBCS ═══ If all the characters are SBCS, true is returned. public: Boolean isSBCS() const; ═══ 1.11.21. IDBCSBuffer::isValidDBCS ═══ If no DBCS characters have a 0 second byte, true is returned. public: Boolean isValidDBCS() const; ═══ 1.11.22. IDBCSBuffer::isValidMBCS ═══ If no MBCS characters have a 0 second byte, true is returned. public: Boolean isValidMBCS() const; ═══ 1.11.23. IDBCSBuffer::lastIndexOf ═══ Returns the index of the last occurrence of the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The returned value is in the range 0 <= x <= startPos. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 or 1for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = 1) const; Overload 2 public: unsigned lastIndexOf( const char* pString, unsigned len, unsigned startPos = 0) const; ═══ 1.11.24. IDBCSBuffer::lastIndexOfAnyBut ═══ Returns the index of the last character not in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned startPos = 0) const; Overload 2 public: unsigned lastIndexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 0) const; ═══ 1.11.25. IDBCSBuffer::lastIndexOfAnyOf ═══ Returns the index of the last character in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 0 or 1 for startPos, this function returns 0 indicating the search target was not found. Overload 1 public: unsigned lastIndexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 0) const; Overload 2 public: unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned startPos = 0) const; ═══ 1.11.26. IDBCSBuffer::leftJustify ═══ Left-justifies the receiver in a string of the specified length. If the new length (length) is larger than the current length, the string is extended by the pad character (padCharacter). The default pad character is a blank. public: IBuffer* leftJustify(unsigned newLen, char padCharacter); ═══ 1.11.27. IDBCSBuffer::lowerCase ═══ Translates all upper-case letters in the receiver to lower-case. public: IBuffer* lowerCase(); ═══ 1.11.28. IDBCSBuffer::maxCharLength ═══ Returns the maximum number of bytes in a multiple-byte character. This is a static function. protected: static size_t maxCharLength(); ═══ 1.11.29. IDBCSBuffer::next ═══ Returns a pointer to the next character, not the next byte, in the buffer. Overload 1 public: char* next(const char* prev); Overload 2 public: const char* next(const char* prev) const; ═══ 1.11.30. IDBCSBuffer::overlayWith ═══ Replaces a specified portion of the receiver's contents with the specified string. If pos is beyond the end of the receiver's data, it is padded with the pad character (padCharacter). public: IBuffer* overlayWith( const char* overlay, unsigned len, unsigned pos, char padCharacter); ═══ 1.11.31. IDBCSBuffer::prevCharLength ═══ Returns the number of bytes in the preceding character to the one at the specified offset. protected: size_t prevCharLength(unsigned pos) const; ═══ 1.11.32. IDBCSBuffer::remove ═══ Deletes the specified portion of the string (that is, the substring) from the receiver. You can use this function to truncate an IString object at a specific position. For example: aString.remove(8); removes the substring beginning at index 8 and takes the rest of the string as a default. public: IBuffer* remove(unsigned startPos, unsigned numChars); ═══ 1.11.33. IDBCSBuffer::reverse ═══ Reverses the receiver's contents. public: IBuffer* reverse(); ═══ 1.11.34. IDBCSBuffer::rightJustify ═══ Right-justifies the receiver in a string of the specified length. If the receiver's data is shorter than the requested length (length), it is padded on the left with the pad character (padCharacter). The default pad character is a blank. public: IBuffer* rightJustify(unsigned newLen, char padCharacter); ═══ 1.11.35. IDBCSBuffer::startBackwardsSearch ═══ Initializes a search of type IString::lastIndexOf. If searchLen is greater than the length of the buffer, 0 is returned indicating an invalid search request. If the starting position is 0 or beyond the last searchLen bytes of the buffer, the position where the last searchLen bytes start in the buffer is returned. If the starting position is 1 through the last searchLen bytes, the value of startingPos is returned. protected: unsigned startBackwardsSearch( unsigned startPos, unsigned searchLen) const; ═══ 1.11.36. IDBCSBuffer::startSearch ═══ Initializes a search of type IString::indexOf. If startPos is 0, the search uses a starting position of 1. If the specified startPos and searchLen result in an invalid search, 0 is returned. This usually occurs when the sum of startPos and searchLen is greater than the size of the buffer. protected: unsigned startSearch( unsigned startPos, unsigned searchLen) const; ═══ 1.11.37. IDBCSBuffer::strip ═══ Strips both leading and trailing character or characters. You can specify the character or characters as the following: A char* array An IStringTestobject The default is white space. Overload 1 public: IBuffer* strip( const IStringTest& aTest, IStringEnum::StripMode mode); Overload 2 public: IBuffer* strip( const char* pChars, unsigned len, IStringEnum::StripMode mode); ═══ 1.11.38. IDBCSBuffer::subString ═══ Returns a new IBuffer, of the same type as the previous one, containing the specified subset of characters. The parameters are the following: startPos The index at which to start the substring. If startPos is 0, the function uses position 1. If startPos is beyond the end of the buffer, nothing is copied. The buffer is filled out by the specified padding character. len The length to copy from the buffer. If the length extends beyond the end of the buffer, only the portion up to the end is copied. The buffer is then padded. If len is 0, a reference to the NULL buffer is returned. padCharacter Specifies the character the function uses to pad the copied string if less than len bytes have been copied from the source buffer. public: IBuffer* subString( unsigned startPos, unsigned len, char padCharacter) const; ═══ 1.11.39. IDBCSBuffer::translate ═══ Converts all of the receiver's characters that are in the first specified string to the corresponding character in the second specified string. public: IBuffer* translate( const char* pInputChars, unsigned inputLen, const char* pOutputChars, unsigned outputLen, char padCharacter); ═══ 1.11.40. IDBCSBuffer::upperCase ═══ Translates all lower-case letters in the receiver to upper-case. public: IBuffer* upperCase(); ═══ 1.11.41. IDBCSBuffer::~IDBCSBuffer ═══ protected: ~IDBCSBuffer(); ═══ 1.12. IDeviceError ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IDeviceError ═══ IException │ IDeviceError Inherited by none. ═══ Class Description - IDeviceError ═══ iexcbase.hpp Objects of the IDeviceError class represent an exception. When a member function makes a hardware-related request of the operating system or the presentation system that the system cannot satisfy because of a hardware failure, the member function creates and throws an object of the IDeviceError class. An example of a failing hardware-related request is printing to a disconnected printer. ═══ Public Functions - IDeviceError ═══ Constructors IDeviceError Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IDeviceError - Constructors ═══ You can construct objects of this class. ═══ IDeviceError - Exception Type ═══ These members provide support for determining the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IDeviceError ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.12.1. IDeviceError::IDeviceError ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IDeviceError( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.12.2. IDeviceError::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.13. IErrorInfo ═══ Description Derivation Constructors Public Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IErrorInfo ═══ IBase │ IVBase │ IErrorInfo Inherited by: ICLibErrorInfo IGUIErrorInfo IMMErrorInfo ISystemErrorInfo IXLibErrorInfo ═══ Class Description - IErrorInfo ═══ iexcept.hpp The IErrorInfo class is an abstract base class that defines the interface for its derived classes. These classes retrieve error information and text that you can subsequently use to create an exception object. The following macros assist in throwing exceptions: IASSERTPARM This macro accepts an expression to test. The expression is asserted to be true. If it evaluates to false, the macro generates code that calls the IExcept__assertParameter function, which creates an IInvalidParameterexception. The error group, other, is added to the object. The exception data is logged using IException::TraceFn::logExceptionData, and the exception is then thrown. IASSERTSTATE This macro accepts an expression to test. The expression is asserted to be true. If it evaluates to false, the macro generates code that calls the IExcept__assertState function, which creates an IInvalidRequestexception. The error group, other, is added to the object. The exception data is logged, and the exception is then thrown. ITHROWLIBRARYERROR This macro can throw any of the User Interface Class Library-defined exceptions. id The ID of the message to load from the class library message file. name A value from the enumeration IErrorInfo::ExceptionType, indicating the type of exception to create. severity A value from the enumeration IException::Severity, indicating the severity of the exception. The macro generates code that calls the IExcept__throwLibraryError function, which does the following: 1. Loads the message text from the class library message file 2. Uses the message text to create an exception object 3. Adds location information 4. Logs the exception data 5. Throws the exception ITHROWLIBRARYERROR1 This macro can throw any of the User Interface Class Library-defined exceptions. It is identical to the ITHROWLIBRARYERROR macro, except it has a fourth parameter: text Replacement text for the retrieved message. ITHROWERROR This macro can throw any of the User Interface Class Library-defined exceptions. messageId The ID of the message to load from the message file. name A value from the enumeration IErrorInfo::ExceptionType, indicating the type of exception to create. severity A value from the enumeration IException::Severity, indicating the severity of the exception. messageFile The name of the message file to load the exception text from. This name should include the file extension. e.g. "USERMSG.MSG" errorGroup The errorGroup associated with this error. This can be one of the values for ErrorCodeGroup defined in IException, or a value you provide. The macro generates code that calls the IExcept__throwError function, which does the following: 1. Loads the message text from the specified library message file 2. Uses the message text to create an exception object 3. Adds the error group to the object 4. Adds location information 5. Logs the exception data 6. Throws the exception ITHROWERROR1 This macro can throw any of the User Interface Class Library-defined exceptions. It is identical to the ITHROWERROR macro, except it has a fourth parameter: substitutionText Substitution text for the retrieved message. Presentation Manager Information IGUIErrorInfo, ISystemErrorInfo, and ICLibErrorInfo are derived from this class. You can use IGUIErrorInfo to obtain information about errors detected by the Win calls for Presentation Manager. Use ISystemErrorInfo to obtain error information about DOS system call errors. Motif Information IXLibErrorInfo is derived from this class. You can use IXLibErrorInfo to obtain error information about error conditions detected when calling X library APIs. Use ICLibErrorInfo to obtain error information about error conditions detected when calling C Library functions. You can create objects of IGUIErrorInfo and ISystemErrorInfo on AIX, but they have default messages: IGUIErrorInfo GUI exception condition detected ISystemErrorInfo System exception condition detected ═══ Public Functions - IErrorInfo ═══ Constructors IErrorInfo ~IErrorInfo Error Information errorId isAvailable operator const char * text Throw Support throwError Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IErrorInfo - Constructors ═══ This is a virtual base class so you cannot create objects of this type without deriving from this class. ═══ IErrorInfo - Error Information ═══ Use these members to return error information provided by objects of this class. All the members are pure virtual. ═══ IErrorInfo - Throw Support ═══ Use these members to support the throwing of exceptions. ═══ Protected Data - IErrorInfo ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.13.1. IErrorInfo::errorId ═══ Returns the error ID. public: virtual unsigned long errorId() const = 0; ═══ 1.13.2. IErrorInfo::IErrorInfo ═══ This is a virtual base class so you cannot create objects of this type without deriving from this class. public: IErrorInfo(); ═══ 1.13.3. IErrorInfo::isAvailable ═══ If error information is available, true is returned. public: virtual Boolean isAvailable() const = 0; ═══ 1.13.4. IErrorInfo::operator const char * ═══ Returns the error text. public: virtual operator const char *() const = 0; ═══ 1.13.5. IErrorInfo::text ═══ Returns the error text. public: virtual const char* text() const = 0; ═══ 1.13.6. IErrorInfo::throwError ═══ Creates an IErrorInfo object and uses it to do the following: 1. Create an exception object 2. Add the error code group to the object 3. Add the location information to the object 4. Log the exception data 5. Throw the exception location An IExceptionLocation object containing the following: Function name File name Line number where the function is called name Use the enumeration ExceptionType to specify the type of the exception. The default is accessError. severity Use the enumeration IException::Severity to specify the severity of the error. The default is recoverable. errorGroup Use one of the ErrorCodeGroup values provided in IException, or provide your own group for this parameter. The default is baseLibrary. public: void throwError( const IExceptionLocation& location, ExceptionType name = accessError, IException::Severity severity = recoverable, IException::ErrorCodeGroup errorGroup = IException::baseLibrary); ═══ 1.13.7. IErrorInfo::~IErrorInfo ═══ public: virtual ~IErrorInfo(); ═══ Nested Types - IErrorInfo ═══ Enumerations ExceptionType ═══ Enums - ExceptionType ═══ enum ExceptionType { accessError, deviceError, invalidParameter, invalidRequest, outOfSystemResource, outOfWindowResource, outOfMemory, resourceExhausted }; The following enumeration type is defined to specify the type of exception to create on various functions and macros: ExceptionType - Used to specify the type of exception to be created. The allowable values are: accessError Creates an IAccessError object. deviceError Creates an IDeviceError object. invalidParameter Creates an IInvalidParameter object. invalidRequest Creates an IInvalidRequest object. outOfSystemResource Creates an IOutOfSystemResource object. outOfWindowResource Creates an IOutOfWindowResource object. outOfMemory Creates an IOutOfMemory object. resourceExhausted Creates an IResourceExhausted object. ═══ 1.14. IException ═══ Description Derivation Constructors Public Functions Public Data Nested Types Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IException ═══ Inherits from none. Inherited by: IAccessError IAssertionFailure IDeviceError IInvalidParameter IInvalidRequest IResourceExhausted ═══ Class Description - IException ═══ iexcbase.hpp The IException class is the base class from which all exception objects thrown in the library are derived. None of the functions in this class throws exceptions because an exception has probably already been thrown or is about to be thrown. Member functions in the User Interface Class Library create objects of classes derived from IException for all error conditions the functions encounter. Each exception object contains the following: A stack of exception message text strings (descriptions) An error ID A severity code An error code group Information about where the exception was thrown IException provides all of the functions required for it and its derived classes, including functions that operate on the text strings in the stack. The library defines the derived classes so that you can catch exceptions by their type. In general, never create an IException object. Instead, create and throw an object of the appropriate derived class. The derived classes of IException are the following: IAccessError IAssertionFailure IDeviceError IInvalidParameter IInvalidRequest IResourceExhausted In addition, IResourceExhausted has the following derived classes: IOutOfMemory IOutOfSystemResource IOutOfWindowResource You can also derive your own exception type from IException. The User Interface Class Library provides the following macros to assist in using exception handling. If you derive your own exception type and you want to use a macro, you must use the ITHROW macro or write your own macro. ITHROW Accepts as input a predefined object of any IException-derived class. The macro generates code to add the location information to the objects, logs all object data, and throws the exception. IRETHROW Accepts as input an object of any derived class of IException that has been previously thrown and caught. Like the ITHROW macro, it also captures the location information and logs all object data before re-throwing the exception. IASSERT If you define IC_DEVELOP during the compile for debugging purposes, this macro expands to provide assertion support in the library. This macro accepts an expression to test. If the test evaluation returns false, IASSERT calls assertParameter. IEXCLASSDECLARE Creates a declaration for a derived class of IException or one of its derived classes. IEXCLASSIMPLEMENT Creates a definition for a derived class of IException or one of its derived classes. IEXCEPTION_LOCATION Expands to create an object of the class IExceptionLocation. INO_EXCEPTIONS_SUPPORT Supports compilers lacking an exception-handling implementation. If you use the INO_EXCEPTIONS_SUPPORT macro, the following macros end the program after capturing the location information and logging it. These macros normally throw an exception. ITHROW Found in IException. IASSERTPARM Found in IErrorInfo. IASSERTSTATE Found in IErrorInfo. ITHROWERROR Found in IErrorInfo. ITHROWERROR1 Found in IErrorInfo. ITHROWLIBRARYERROR Found in IErrorInfo. ITHROWLIBRARYERROR1 Found in IErrorInfo. ITHROWGUIERROR Found in IGUIErrorInfo. ITHROWGUIERROR2 Found in IGUIErrorInfo. ITHROWSYSTEMERROR Found in ISystemErrorInfo. Warning: The INO_EXCEPTIONS_SUPPORT macro might not work correctly on all compilers. Whenever the User Interface Class Library throws one of these exceptions, trace records are output with information about the exception. The class ITrace describes tracing in more detail. ═══ Public Functions - IException ═══ Application Termination terminate Constructors IException ~IException Error Code errorCodeGroup setErrorCodeGroup Error Information errorId setErrorId Exception Location addLocation locationAtIndex locationCount Exception Logging logExceptionData setTraceFunction Exception Severity isRecoverable setSeverity Exception Text appendText setText text textCount Exception Type name Throw Support assertParameter ═══ IException - Application Termination ═══ These members provide support for terminating an application instead of throwing an exception. ═══ IException - Constructors ═══ You can construct and destruct objects of this class. You cannot assign one IException object from another. ═══ IException - Error Code ═══ Use these members to determine which class library an exception originated from. ═══ IException - Error Information ═══ Use these members to get or modify the error identifier of the exception object. ═══ IException - Exception Location ═══ Use these members to set and access the location information in the exception object. ═══ IException - Exception Logging ═══ Use these members to log exception information. ═══ IException - Exception Severity ═══ Use these members to set and determine the severity of the error condition. ═══ IException - Exception Text ═══ Use these members to set, modify, and retrieve the exception text in the object. ═══ IException - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ IException - Hidden Functions ═══ These members are hidden to prevent you from copying objects of this class. ═══ IException - Throw Support ═══ These members support the throwing of exceptions. ═══ Public Data - IException ═══ Error Code baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.14.1. IException::addLocation ═══ Adds the location information to the exception object. The User Interface Class Library captures this information when an exception is thrown or re-thrown. An array of IExceptionLocation objects is stored in the exception object. location An IExceptionLocation object containing the following: Function name File name Line number where the function is called public: virtual IException& addLocation( const IExceptionLocation& location); ═══ 1.14.2. IException::appendText ═══ Appends the specified text to the text string on the top of the exception text stack. errorText The text you want to append. public: IException& appendText(const char* errorText); ═══ 1.14.3. IException::assertParameter ═══ The IASSERT macro uses this function to do the following: 1. Create an IAssertionFailure exception 2. Add the location information to it 3. Log the exception data 4. Throw the exception exceptionText The text describing the exception. location An IExceptionLocation object containing the following: Function name File name Line number where the function is called public: static void assertParameter( const char* exceptionText, IExceptionLocation location); ═══ 1.14.4. IException::baseLibrary ═══ This is the error group for IBM Open Class Library errors. public: static ErrorCodeGroup const baseLibrary; ═══ 1.14.5. IException::CLibrary ═══ This is the error group for the C library errors. public: static ErrorCodeGroup const CLibrary; ═══ 1.14.6. IException::errorCodeGroup ═══ Returns the error group the exception originated from. public: ErrorCodeGroup errorCodeGroup() const; ═══ 1.14.7. IException::errorId ═══ Returns the error ID of the exception. public: unsigned long errorId() const; Used in sample: List Box Sample: alistbox.cpp ═══ 1.14.8. IException::IException ═══ You can construct and destruct objects of this class. You cannot assign one IException object from another. Overload 1 public: IException(const IException& exception); The copy constructor is provided so that the compiler can make copies of the object during the throwing of an exception. Overload 2 public: IException( const char* errorText, unsigned long errorId = 0, Severity severity = IException::unrecoverable); You can construct objects of this class by doing the following: Using the primary constructor. Normally, this is the only way you can construct an object of this class. errorText The text describing this error. errorId (Optional) The identifier you want to associate with this particular error. severity (Optional) Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the copy constructor. The User Interface Class Library provides this constructor so the compiler can copy the exception when it is thrown. exception The exception object you want to copy. ═══ 1.14.9. IException::isRecoverable ═══ If the thrower (that is, whatever creates the exception) determines the exception is recoverable, 1 is returned. If the thrower determines it is unrecoverable, 0 is returned. public: virtual int isRecoverable() const; ═══ 1.14.10. IException::locationAtIndex ═══ Returns the IExceptionLocation object at the specified index. locationIndex If the index is not valid, a 0 pointer is returned. public: const IExceptionLocation* locationAtIndex( unsigned long locationIndex) const; ═══ 1.14.11. IException::locationCount ═══ Returns the number of locations stored in the exception location array. public: unsigned long locationCount() const; ═══ 1.14.12. IException::logExceptionData ═══ Logs the exception data stored in the IException object using the function specified by IException::setTraceFunction. If you have not set a tracing function, the exception information is written to standard error output. public: virtual IException& logExceptionData(); ═══ 1.14.13. IException::name ═══ Returns the name of the object's class. public: virtual const char* name() const; Used in sample: List Box Sample: alistbox.cpp ═══ 1.14.14. IException::operatingSystem ═══ This is the error group for operating system errors. public: static ErrorCodeGroup const operatingSystem; ═══ 1.14.15. IException::other ═══ This is the error group for errors which don't fall in any of the other groups. public: static ErrorCodeGroup const other; ═══ 1.14.16. IException::presentationSystem ═══ This is the error group for presentation system errors. public: static ErrorCodeGroup const presentationSystem; ═══ 1.14.17. IException::setErrorCodeGroup ═══ Sets the id of the originating class library into the exception object. public: IException& setErrorCodeGroup(ErrorCodeGroup errorGroup); ═══ 1.14.18. IException::setErrorId ═══ Sets the error ID to the specified value. errorId The identifier you want to associate with this error. public: IException& setErrorId(unsigned long errorId); ═══ 1.14.19. IException::setSeverity ═══ Sets the severity of the exception. severity Use the enumeration Severity to specify the severity of the exception. public: IException& setSeverity(Severity severity); ═══ 1.14.20. IException::setText ═══ Adds the specified text to the top of the exception text stack. errorText The error text you want to add. public: IException& setText(const char* errorText); ═══ 1.14.21. IException::setTraceFunction ═══ Registers an object of IException::TraceFn to be used to log exception data. The ITrace member functions and macros write the trace messages. IException::logExceptionData calls IException::TraceFn::write during exception processing to write the data. If you do not register an object, data is written to standard error output. traceFunction Your own trace function implementation. public: static void setTraceFunction( IException::TraceFn& traceFunction); ═══ 1.14.22. IException::terminate ═══ Ends the application. Normally, the User Interface Class Library only intends this function to be used internally by the library's exception handling macros when the compiler you are using does not support C++ exception handling. This only occurs if you define the INO_EXCEPTIONS_SUPPORT macro. The macros that use this function are: ITHROW Found in IException. IASSERTPARM Found in IErrorInfo. IASSERTSTATE Found in IErrorInfo. ITHROWLIBRARYERROR Found in IErrorInfo. ITHROWLIBRARYERROR1 Found in IErrorInfo ITHROWGUIERROR Found in IGUIErrorInfo. ITHROWGUIERROR2 Found in IGUIErrorInfo. ITHROWSYSTEMERROR Found in ISystemErrorInfo. public: virtual void terminate(); ═══ 1.14.23. IException::text ═══ Returns a constant char* pointing to an exception text string from the exception text stack. indexFromTop The default index is 0, which is the top of the stack. If you specify an index which is not valid, a 0 pointer is returned. public: const char* text(unsigned long indexFromTop = 0) const; Used in samples: List Box Sample: alistbox.cpp Lancelot - A Valiant Example: linfonb.cpp ═══ 1.14.24. IException::textCount ═══ Returns the number of text strings in the exception text stack. public: unsigned long textCount() const; Used in sample: List Box Sample: alistbox.cpp ═══ 1.14.25. IException::~IException ═══ public: virtual ~IException(); ═══ Nested Types - IException ═══ Classes IException::TraceFn Enumerations Severity Type Definitions ErrorCodeGroup ═══ Enums - Severity ═══ enum Severity { unrecoverable, recoverable }; Use these enumerators to specify the severity of the exception: unrecoverable Classifies the exception as unrecoverable. recoverable Classifies the exception as recoverable. ═══ Type Definition - IException::ErrorCodeGroup ═══ typedef const char * ErrorCodeGroup; This identifies the source of the exception's error code. ═══ 1.15. IException::TraceFn ═══ Description Derivation Public Functions Protected Functions To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IException::TraceFn ═══ Inherits from none. Inherited by none. ═══ Class Description - IException::TraceFn ═══ iexcbase.hpp Objects of the class IException and its derived classes use IException::TraceFn to log exception object data. A default TraceFn derived object is registered by the Collection Class Library. If the User Interface Library is used, it registers a TraceFn derived object which overrides the write function. It uses ITrace to write out the buffers of data, so the buffers will be written to wherever the ICLUI TRACETO environment variable directs the output from ITrace. If you want to provide your own tracing function, derive your own class from IException::TraceFn and register it with IException using IException::setTraceFunction. You can completely take over exception logging by overriding the logData function. You are passed the IException object so you can completely customize the logging of exception data. If you only wish to change how the buffers of exception data are logged you should override the write function. The exceptionLogged function is provided so that you can determine when the last buffer of exception data has been passed to the write function by the default logData function. This allows you to gather all of the exception data by only overriding the write and exceptionLogged functions for situations where you must write all of the exception data out with one call. ═══ Public Functions - IException::TraceFn ═══ Tracing logData write ═══ IException::TraceFn - Constructors ═══ The only way to create objects of this class is from a derived class. To enforce this, the only constructors we provide for this class are protected. Derived classes use these members to create objects of this class. ═══ IException::TraceFn - Tracing ═══ The IException's logExceptionData member uses these members to log instance data of exception objects. ═══ Protected Functions - IException::TraceFn ═══ Constructors TraceFn Tracing exceptionLogged ═══ 1.15.1. IException::TraceFn::exceptionLogged ═══ This function is called by the default logData function after the last buffer of exception data has been passed to the write function. protected: virtual void exceptionLogged(); ═══ 1.15.2. IException::TraceFn::logData ═══ Logs error information contained in an Exception object. public: virtual void logData(IException& exception); ═══ 1.15.3. IException::TraceFn::TraceFn ═══ This default constructor can be used by derived classes to create objects of this class. protected: TraceFn(); ═══ 1.15.4. IException::TraceFn::write ═══ Writes a buffer of exception data. public: virtual void write(const char* buffer); ═══ 1.16. IExceptionLocation ═══ Description Derivation Constructors Public Functions To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IExceptionLocation ═══ Inherits from none. Inherited by none. ═══ Class Description - IExceptionLocation ═══ iexcbase.hpp Objects of the IExceptionLocation class save the location information when an exception is thrown or re-thrown. None of the functions in this class throws exceptions because an exception probably has been thrown already or is about to be thrown. Typically, either the ITHROW or IRETHROW macro creates an IExceptionLocation object when an exception is to be thrown or re-thrown, respectively. However, you can create your own IExceptionLocation object by constructing it yourself or by using the IEXCEPTION_LOCATION macro. ═══ Public Functions - IExceptionLocation ═══ Attributes fileName functionName lineNumber Constructors IExceptionLocation ═══ IExceptionLocation - Attributes ═══ Use these members to return the attributes of the exception location object. ═══ IExceptionLocation - Constructors ═══ You can construct objects of this class. ═══ 1.16.1. IExceptionLocation::fileName ═══ Returns the path-qualified source file name where an exception has been thrown or re-thrown. public: const char* fileName() const; ═══ 1.16.2. IExceptionLocation::functionName ═══ Returns the name of the function that has thrown or re-thrown an exception. public: const char* functionName() const; ═══ 1.16.3. IExceptionLocation::IExceptionLocation ═══ You can create objects of this class by doing the following: Using the constructor. fileName The source file containing the function that created this object. functionName The name of the function creating this object. lineNumber The line number of the statement from the source file from which the object was created. Using the macro IEXCEPTION_LOCATION. This macro captures the current location information using constants provided by the compiler for all of the parameters. Default values are provided for all the parameters to support environments in which all constants or alternative means for getting location information are not provided. public: IExceptionLocation( const char* fileName = 0, const char* functionName = 0, unsigned long lineNumber = 0); ═══ 1.16.4. IExceptionLocation::lineNumber ═══ Returns the line number of the statement in the source file from which an exception has been thrown or re-thrown. public: unsigned long lineNumber() const; ═══ 1.17. IGUIErrorInfo ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IGUIErrorInfo ═══ IBase │ IVBase │ IErrorInfo │ IGUIErrorInfo Inherited by none. ═══ Class Description - IGUIErrorInfo ═══ iexcept.hpp Objects of the IGUIErrorInfo class represent error information that you can include in an exception object. When an OS/2 Win call results in an error condition, objects of the IGUIErrorInfo class are created. You can use the error text to construct a derived class object of IException. The User Interface Class Library provides the following macros for throwing exceptions constructed with IGUIErrorInfo information: ITHROWGUIERROR This macro accepts as its only parameter the name of the GUI function that returned an error condition. This macro then generates code that calls IGUIError::throwGUIError, which does the following: 1. Creates an IGUIErrorInfo object 2. Uses the object to create an object of IAccessError 3. Adds the presentationSystem error group to the object 4. Adds location information 5. Logs the exception data 6. Throws the exception Note: This macro uses the recoverable enumerator provided by IException::Severity. ITHROWGUIERROR2 This macro can throw any of the User Interface Class Library-defined exceptions. This macro accepts the following parameters: location The name of the GUI function returning an error code, the name of the file the function is in, and the function's line number. name Use the enumeration IErrorInfo::ExceptionType to specify the type of the exception. The default is accessError. severity Use the enumeration IException::Severity to specify the severity of the error. The default is recoverable. This macro generates code that calls throwGUIError, which does the following: 1. Creates an IGUIErrorInfo object 2. Uses the object to create an IException object 3. Adds the presentationSystem error group to the object 4. Adds location information 5. Logs the exception data 6. Throws the exception Portability Considerations You can use this class in OS/2 to create error information for GUI errors resulting from Win calls. Objects of this class obtain the error information by calling WinGetLastError, which is the Presentation Manager API that maintains the error information per thread. Motif does not have a similar mechanism where you can query the X server for error information. If you use objects of this class in AIX, they obtain a default message, which is "GUI exception condition detected." Presentation Manager Information You can use objects of the IGUIErrorInfo class to obtain information about the last error that occurred on a call to Presentation Manager. Motif Information You can create objects of this class on AIX, but the objects contain no useful information and only have the default message: "GUI exception condition detected." ═══ Public Functions - IGUIErrorInfo ═══ Constructors IGUIErrorInfo ~IGUIErrorInfo Error Information errorId isAvailable operator const char * text Throw Support throwGUIError Inherited Members IErrorInfo errorId isAvailable operator const char * text throwError IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IGUIErrorInfo - Constructors ═══ You can construct and destruct objects of this class. You cannot copy or assign objects of this class. ═══ IGUIErrorInfo - Error Information ═══ Use these members to return error information provided by objects of this class. ═══ IGUIErrorInfo - Hidden Functions ═══ These members are hidden to prevent you from copying objects of this class. ═══ IGUIErrorInfo - Throw Support ═══ Use these members to support the throwing of exceptions using information from an IGUIErrorInfo object. The throwGUIError function is used by the ITHROWGUIERROR macro. ═══ Protected Data - IGUIErrorInfo ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.17.1. IGUIErrorInfo::errorId ═══ Returns the error ID. public: virtual unsigned long errorId() const; Presentation Manager: In the case of a Presentation Manager error, the IGUIErrorInfo constructor obtains the errorId using WinGetLastError. ═══ 1.17.2. IGUIErrorInfo::IGUIErrorInfo ═══ You can construct and destruct objects of this class. You cannot copy or assign objects of this class. public: IGUIErrorInfo(const char* GUIFunctionName = 0); You can only construct objects of this class using the default constructor. Note: If the constructor cannot load the error text, the User Interface Class Library provides the following default text: "No error text is available." GUIFunctionName The name of the failing GUI function. If you specify GUIFunctionName, the constructor prefixes it to the error text. Optional. ═══ 1.17.3. IGUIErrorInfo::isAvailable ═══ If the error information is available, true is returned. public: virtual Boolean isAvailable() const; ═══ 1.17.4. IGUIErrorInfo::operator const char * ═══ Returns the error text. public: virtual operator const char *() const; ═══ 1.17.5. IGUIErrorInfo::text ═══ Returns the error text. public: virtual const char* text() const; ═══ 1.17.6. IGUIErrorInfo::throwGUIError ═══ Creates an IGUIErrorInfo object and uses the text from it to do the following: 1. Create an exception object 2. Add the location information to it 3. Log the exception data 4. Throw the exception. functionName The name of the function where the exception occurred. location An IExceptionLocation object containing the following: Function name File name Line number where the function is called name Use the enumeration IErrorInfo::ExceptionType to specify the type of the exception. The default is accessError. severity Use the enumeration IException::Severity to specify the severity of the error. The default is recoverable. public: static void throwGUIError( const char* functionName, const IExceptionLocation& location, IErrorInfo::ExceptionType name = accessError, IException::Severity severity = recoverable); ═══ 1.17.7. IGUIErrorInfo::~IGUIErrorInfo ═══ public: virtual ~IGUIErrorInfo(); ═══ 1.18. IInvalidParameter ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IInvalidParameter ═══ IException │ IInvalidParameter Inherited by none. ═══ Class Description - IInvalidParameter ═══ iexcbase.hpp Objects of the IInvalidParameter class represent an exception. When a member function detects an invalid input parameter, the member function creates and throws an object of the IInvalidParameter class. This exception is identical to the exception IAssertionFailure, with one difference: IInvalidParameter is thrown whether or not you define IC_DEVELOP for the compile. ═══ Public Functions - IInvalidParameter ═══ Constructors IInvalidParameter Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IInvalidParameter - Constructors ═══ You can construct objects of this class. ═══ IInvalidParameter - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IInvalidParameter ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.18.1. IInvalidParameter::IInvalidParameter ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IInvalidParameter( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.18.2. IInvalidParameter::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.19. IInvalidRequest ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IInvalidRequest ═══ IException │ IInvalidRequest Inherited by none. ═══ Class Description - IInvalidRequest ═══ iexcbase.hpp Objects of the IInvalidRequest class represent an exception. Whenever an object cannot satisfy a request, the member function creates and throws an object of the IInvalidRequest class. An example of such a request occurs if you try to paste text from the system clipboard, but the clipboard has no data. ═══ Public Functions - IInvalidRequest ═══ Constructors IInvalidRequest Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IInvalidRequest - Constructors ═══ You can construct objects of this class. ═══ IInvalidRequest - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IInvalidRequest ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.19.1. IInvalidRequest::IInvalidRequest ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IInvalidRequest( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.19.2. IInvalidRequest::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.20. IMessageText ═══ Description Derivation Constructors Public Functions To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IMessageText ═══ Inherits from none. Inherited by none. ═══ Class Description - IMessageText ═══ imsgtext.hpp Objects of the IMessageText class load message text from a message file. When the User Interface Class Library detects an error condition and prepares to throw an exception, the library creates an object of this class if it is using customized message text. You can use the message text provided by this class to construct an object of a class derived from IException. Presentation Manager Information The IMessageText object searches for the message file as follows: The system root directory The current working directory The DPATH environment setting The APPEND environment setting Typically, message files have the extension .MSG. Motif Information The IMessageText object searches for the message file using the NLSPATH environment setting. ═══ Public Functions - IMessageText ═══ Constructors IMessageText operator = ~IMessageText Text Operations operator const char * setDefaultText text ═══ IMessageText - Constructors ═══ You can construct, destruct, copy, and assign objects of this class. ═══ IMessageText - Text Operations ═══ Use these members to obtain the text from the object and to set the default text for the object. ═══ 1.20.1. IMessageText::IMessageText ═══ You can construct, destruct, copy, and assign objects of this class. Overload 1 public: IMessageText( unsigned long messageId, const char* messageFileName, const char* textInsert1 = 0, const char* textInsert2 = 0, const char* textInsert3 = 0, const char* textInsert4 = 0, const char* textInsert5 = 0, const char* textInsert6 = 0, const char* textInsert7 = 0, const char* textInsert8 = 0, const char* textInsert9 = 0); You can construct objects of this class using this constructor, allowing you to retrieve a message from a file and, optionally, insert additional text strings within the retrieved message. You can specify that the object insert the text strings through substitution symbols within the message. For example: The application cannot find the file, %1, at the specified path, %2. Using this constructor, you can replace the substitution symbols by supplying the file name and path name via textInsert1 and textInsert2 respectively. Notice the substitution symbol number (%1) matches the parameter number (textInsert1). Warning: You must use the numbers in sequence. For example, you cannot use %1, %2, and %5 in a message, skipping %3 and %4. Instead, you must use %1, %2, and %3. You must specify the substitution symbols sequentially and the text insertion parameters' numbers must match their respective substitution symbol. messageId The message ID. messageFileName The name of the message file to retrieve the message from. The message file name must include the file extension. If you specify 0, the message text is in a message segment bound to the .EXE. The IMessageText object loads the message from the application. Otherwise, the library searches for the message text in the specified message file. Note: If the User Interface Class Library cannot load the text from the message file, this constructor uses the following default text: "Unable to load text from message file." textInsert1 through textInsert9 (Optional) A text string you insert into the message. Overload 2 public: IMessageText(const IMessageText& text); You can construct objects of this class using the User Interface Class Library provided copy constructor. text The error message text. ═══ 1.20.2. IMessageText::operator = ═══ Sets the object data to the values of the specified IMessageText object. text The message text object you want to copy. public: IMessageText& operator =(const IMessageText& text); ═══ 1.20.3. IMessageText::operator const char * ═══ Returns the message text. public: operator const char *() const; ═══ 1.20.4. IMessageText::setDefaultText ═══ Sets the default message text to the specified text string. The text is set only if the constructor cannot load the text for the specified message ID. Note: The default text is: "Unable to load text from message file." text The new default text string. public: IMessageText& setDefaultText(const char* text); ═══ 1.20.5. IMessageText::text ═══ Returns the message text. public: const char* text() const; ═══ 1.20.6. IMessageText::~IMessageText ═══ public: ~IMessageText(); ═══ 1.21. INotificationEvent ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - INotificationEvent ═══ IBase │ INotificationEvent Inherited by none. ═══ Class Description - INotificationEvent ═══ inotifev.hpp The class INotificationEvent provides the details of a notification event to an observer object. INotifier objects create notification events when these objects change or when they must notify observer objects of events. All IBM User Interface Class Library classes may inherit from the INotifier class to obtain the ability to notify. Currently, the IBM User Interface Class Library has implemented the IWindowclass as inheriting from INotifier. Therefore, all classes derived from IWindowinherit this ability. ═══ Public Functions - INotificationEvent ═══ Constructors INotificationEvent operator = ~INotificationEvent Event Attributes eventData hasNotifierAttrChanged notificationId notifier observerData setEventData setNotifierAttrChanged setObserverData Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ INotificationEvent - Constructors ═══ You can construct, destruct, and assign objects of this class. ═══ INotificationEvent - Event Attributes ═══ Use these members to get and set the attributes of objects of this class. ═══ Protected Data - INotificationEvent ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.21.1. INotificationEvent::eventData ═══ Returns the data specific to the event. public: IEventData eventData() const; Used in samples: Notify Sample: notify.cpp Multimedia MMREMOTE Sample: mmremote.cpp Multimedia MMSTEREO Sample: mltcd.cpp Multimedia MMSTEREO Sample: mltvid.cpp Multimedia MMSTEREO Sample: mltwave.cpp ═══ 1.21.2. INotificationEvent::hasNotifierAttrChanged ═══ Returns true if the event represents a change in an attribute of the notifier object. public: Boolean hasNotifierAttrChanged() const; ═══ 1.21.3. INotificationEvent::INotificationEvent ═══ You can construct, destruct, and assign objects of this class. Overload 1 public: INotificationEvent(const INotificationEvent& event); You can construct an INotificationEvent object using a copy of an existing notification event. Overload 2 public: INotificationEvent( const INotificationId& identifier, INotifier& notifier, Boolean notifierAttrChanged = true, const IEventData& eventData = IEventData ( ), const IEventData& observerData = IEventData ( )); You can construct an INotificationEvent object using a notification identifier, a reference to a notifier object derived from INotifier, and a Boolean indicator of whether this event describes a change in an attribute of the notifier. The notifier can also include data specific to the particular notification. This data is documented with the notification IDs in the definition of the derived notifier class. The notifier must also add observer data to the event if the observer provided this data when registering with the notifier. ═══ 1.21.4. INotificationEvent::notificationId ═══ Returns the INotificationId for the event. The derived INotifier classes document the notification identifiers. public: INotificationId notificationId() const; Used in samples: Notify Sample: notify.cpp Multimedia MMREMOTE Sample: mmremote.cpp Multimedia MMSTEREO Sample: mltcd.cpp Multimedia MMSTEREO Sample: mltvid.cpp Multimedia MMSTEREO Sample: mltwave.cpp ═══ 1.21.5. INotificationEvent::notifier ═══ Returns a reference to the notifier object. public: INotifier& notifier() const; Used in sample: Notify Sample: notify.cpp ═══ 1.21.6. INotificationEvent::observerData ═══ Returns observer data that is added when the observer registers with the notifier object. public: IEventData observerData() const; ═══ 1.21.7. INotificationEvent::operator = ═══ Replaces the contents of one INotificationId object with another INotification object. public: INotificationEvent& operator =( const INotificationEvent& event); ═══ 1.21.8. INotificationEvent::setEventData ═══ Stores event data that is specific to a particular notification. The existence and type of the event data is documented with the notification IDs in the definition of the derived notifier class. public: INotificationEvent& setEventData( const IEventData& eventData); ═══ 1.21.9. INotificationEvent::setNotifierAttrChanged ═══ Indicates that the notification event is a change in one of the notifier's attributes. public: INotificationEvent& setNotifierAttrChanged( Boolean notifierAttrchanged = true); ═══ 1.21.10. INotificationEvent::setObserverData ═══ Stores observer data in the notification event. The observer provides this data when it registers with a notifier by calling the INotifier::addObserver protected member function. public: INotificationEvent& setObserverData( const IEventData& observerData); ═══ 1.21.11. INotificationEvent::~INotificationEvent ═══ public: ~INotificationEvent(); ═══ 1.22. INotifier ═══ Description Derivation Constructors Public Functions Protected Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - INotifier ═══ IBase │ IVBase │ INotifier Inherited by: IStandardNotifier IWindow ═══ Class Description - INotifier ═══ inotify.hpp The class INotifier defines the notification protocol that objects that support observation must supply. Because this class is an abstract base class, you cannot construct objects of this class. All IBM User Interface Class Library window classes inherit the notification process from INotifier. You can implement a notification protocol in the following way: Derive a class from the IStandardNotifier class which inherits from INotifier for a direct implementation of the INotifier protocol Derive from the INotifier class and implement your own notification protocol Because IWindow inherits from and implements the INotifier protocol, IWindow provides a visual implementation. IStandardNotifier inherits from INotifier and can be used for any generic notifier, visual or not. You might want to derive your classes from IStandardNotifier if you are providing a nonvisual notifier. INotifier objects define INotificationIds for each notification that the derived class provides. You should document the details of these notifications, including any notifier data, within the description of the notification IDs of the derived class definition. INotifier objects notify their observers of all events after the observer requests notification by calling INotifier::addObserver. The observer object must check the notification ID and process the events it is interested in. Presentation Manager Information See Building VisualAge C++ Parts for Fun and Profit for more information on part construction. ═══ Public Functions - INotifier ═══ Constructors INotifier ~INotifier Notification Members disableNotification enableNotification isEnabledForNotification Observer Notification notifyObservers Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ INotifier - Constructors ═══ This class is an abstract base class therefore objects cannot be constructed. ═══ INotifier - Notification Members ═══ Use these members to affect the ability of INotifier to notify observers of events. ═══ INotifier - Observer Addition and Removal ═══ IObserver objects use these members to add and remove themselves from the notifier's collection. ═══ INotifier - Observer Notification ═══ These members notify observers of a change in a notifier. ═══ Protected Functions - INotifier ═══ Observer Addition and Removal addObserver observerList removeAllObservers removeObserver Observer Notification notifyObservers ═══ Protected Data - INotifier ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.22.1. INotifier::addObserver ═══ Adds an observer to the notifier's list of observers. protected: virtual INotifier& addObserver( IObserver& observer, const IEventData& userData) = 0; ═══ 1.22.2. INotifier::disableNotification ═══ Stops the notifier from sending notifications to its observers. public: virtual INotifier& disableNotification() = 0; ═══ 1.22.3. INotifier::enableNotification ═══ Starts the notifier sending notifications to its observers. This function can be overridden by derived classes to perform customized notification that your application might need. For instance, one of your function methods may require that a data base be accessible before processing a retrieve function. public: virtual INotifier& enableNotification( Boolean enable = true) = 0; ═══ 1.22.4. INotifier::INotifier ═══ This class is an abstract base class therefore objects cannot be constructed. public: INotifier(); ═══ 1.22.5. INotifier::isEnabledForNotification ═══ Returns true if a notifier can send notifications to its observers. public: virtual Boolean isEnabledForNotification() const = 0; ═══ 1.22.6. INotifier::notifyObservers ═══ Notifies all observers in a notifier's list of observers. Each observer receives a notification event containing the identity of the notifier, the notification ID, and any optional data provided by the specific notifier object. Note: A public and a protected version of notifyObservers are provided for convenience. The protected version does not require the caller to construct an INotificationEvent to call it. In this case, the construction of the INotificationEvent occurs in the code of the protected notifyObservers function. Overload 1 public: virtual INotifier& notifyObservers( const INotificationEvent& event) = 0; Overload 2 protected: virtual INotifier& notifyObservers( const INotificationId& id) = 0; ═══ 1.22.7. INotifier::observerList ═══ Returns the list of observers. If the observer list does not exist, the derived notifier class must create it before calling this member function. protected: virtual IObserverList& observerList() const = 0; ═══ 1.22.8. INotifier::removeAllObservers ═══ Removes all observers from the notifier's list of observers. protected: virtual INotifier& removeAllObservers() = 0; ═══ 1.22.9. INotifier::removeObserver ═══ Removes an observer from the notifier's list of observers. protected: virtual INotifier& removeObserver(IObserver& observer) = 0; ═══ 1.22.10. INotifier::~INotifier ═══ public: virtual ~INotifier(); ═══ 1.23. IObserver ═══ Description Derivation Public Functions Protected Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IObserver ═══ IBase │ IVBase │ IObserver Inherited by none. ═══ Class Description - IObserver ═══ iobservr.hpp The IObserver class is the abstract base class for all objects that are to be notified of changes in the state of other objects in the system. You can derive objects that require notification from this class and implement the function dispatchNotificationEvent to process specific events. ═══ Public Functions - IObserver ═══ Constructors ~IObserver Event Dispatching handleNotificationsFor stopHandlingNotificationsFor Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IObserver - Constructors ═══ Only derived classes can create objects of this class. To enforce this, the only constructor has protected access. ═══ IObserver - Event Dispatching ═══ Use these members to evaluate events and determine if it is appropriate for an observer object to process it. They also attach the observer to and detach the observer from the INotifier object. ═══ Protected Functions - IObserver ═══ Constructors IObserver Event Dispatching dispatchNotificationEvent ═══ Protected Data - IObserver ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.23.1. IObserver::dispatchNotificationEvent ═══ Notifies an observer of an event in a notification enabled object. The notification also includes event specific information. protected: virtual IObserver& dispatchNotificationEvent( const INotificationEvent& event) = 0; ═══ 1.23.2. IObserver::handleNotificationsFor ═══ Attaches the observer to the INotifier object argument. The observer is notified of events after the notifier object has been enabled for notifications. public: virtual IObserver& handleNotificationsFor( INotifier& notifier, const IEventData& userData = IEventData ( )); Used in samples: Notify Sample: notify.cpp Multimedia MMREMOTE Sample: mmremote.cpp Multimedia MMSTEREO Sample: mltcd.cpp Multimedia MMSTEREO Sample: mltvid.cpp Multimedia MMSTEREO Sample: mltwave.cpp ═══ 1.23.3. IObserver::IObserver ═══ The default constructor. protected: IObserver(); ═══ 1.23.4. IObserver::stopHandlingNotificationsFor ═══ Detaches the observer from the argument INotifier object. public: virtual IObserver& stopHandlingNotificationsFor( INotifier& notifier); Used in samples: Multimedia MMSTEREO Sample: mltcd.cpp Multimedia MMSTEREO Sample: mltvid.cpp Multimedia MMSTEREO Sample: mltwave.cpp ═══ 1.23.5. IObserver::~IObserver ═══ public: virtual ~IObserver(); ═══ 1.24. IObserverList ═══ Description Derivation Constructors Public Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IObserverList ═══ IBase │ IVBase │ IObserverList Inherited by none. ═══ Class Description - IObserverList ═══ iobslist.hpp The IObserverList class provides the interface for a list of IObserver objects. This class implements the list of observers as an ordered list that can be traversed with cursor logic. ═══ Public Functions - IObserverList ═══ Constructors IObserverList ~IObserverList Observer Addition and Removal add elementAt isEmpty numberOfElements remove removeAll removeAt Observer Notification notifyObservers Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IObserverList - Constructors ═══ You can construct and destruct objects of this class. ═══ IObserverList - Hidden Functions ═══ ═══ IObserverList - Observer Addition and Removal ═══ Use these members to add, remove, and find IObserver objects in the observer list's collection. ═══ IObserverList - Observer Notification ═══ These members notify observers of a change in a notifier. ═══ Protected Data - IObserverList ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.24.1. IObserverList::add ═══ Adds an observer to the end of the list. public: virtual Boolean add(IObserver& observer, void* userData); ═══ 1.24.2. IObserverList::elementAt ═══ Returns an observer from the list using the specified cursor object. public: virtual IObserver& elementAt(const Cursor& cursor) const; ═══ 1.24.3. IObserverList::IObserverList ═══ You can construct and destruct objects of this class. public: IObserverList(); You may only construct objects of this class using the default constructor that takes no arguments. ═══ 1.24.4. IObserverList::isEmpty ═══ Returns true if there are no observers in the list. public: Boolean isEmpty() const; ═══ 1.24.5. IObserverList::notifyObservers ═══ Traverses the list of observers and calls each member's dispatchNotificationEvent function passing a specified notification event object. public: IObserverList& notifyObservers( const INotificationEvent& event); ═══ 1.24.6. IObserverList::numberOfElements ═══ Returns the number of observers in the list. public: unsigned long numberOfElements() const; ═══ 1.24.7. IObserverList::remove ═══ Removes the specified observer from the list. public: virtual IObserverList& remove(const IObserver& observer); ═══ 1.24.8. IObserverList::removeAll ═══ Removes all observers from the list. public: virtual IObserverList& removeAll(); ═══ 1.24.9. IObserverList::removeAt ═══ Removes an observer at the specified cursor location from the list. public: virtual IObserverList& removeAt(const Cursor& cursor); ═══ 1.24.10. IObserverList::~IObserverList ═══ public: virtual ~IObserverList(); ═══ Nested Types - IObserverList ═══ Classes IObserverList::Cursor ═══ 1.25. IObserverList::Cursor ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IObserverList::Cursor ═══ IBase │ IVBase │ IObserverList::Cursor Inherited by none. ═══ Class Description - IObserverList::Cursor ═══ iobslist.hpp This is a nested cursor class used to iterate over the observers added to an INotifier. ═══ Public Functions - IObserverList::Cursor ═══ Constructors Cursor ~Cursor Cursor Movement invalidate isValid setToFirst setToLast setToNext setToPrevious Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IObserverList::Cursor - Constructors ═══ You can construct and destruct objects of this class. ═══ IObserverList::Cursor - Cursor Movement ═══ These members provide cursor movement operations. ═══ Protected Data - IObserverList::Cursor ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.25.1. IObserverList::Cursor::Cursor ═══ Create an IObserverList::Cursor by providing a reference to an IObserverlist. public: Cursor(IObserverList& observerList); ═══ 1.25.2. IObserverList::Cursor::invalidate ═══ Marks the cursor as invalid. public: virtual void invalidate(); ═══ 1.25.3. IObserverList::Cursor::isValid ═══ Returns true if the cursor is on a valid observer. public: virtual Boolean isValid() const; ═══ 1.25.4. IObserverList::Cursor::setToFirst ═══ Set the cursor position to the first observer in the list. public: virtual Boolean setToFirst(); ═══ 1.25.5. IObserverList::Cursor::setToLast ═══ Sets the cursor position to the last observer in the list. public: virtual Boolean setToLast(); ═══ 1.25.6. IObserverList::Cursor::setToNext ═══ Advances the cursor position to the next observer in the list. public: virtual Boolean setToNext(); ═══ 1.25.7. IObserverList::Cursor::setToPrevious ═══ Sets the cursor position to the prior observer in the list. public: virtual Boolean setToPrevious(); ═══ 1.25.8. IObserverList::Cursor::~Cursor ═══ public: virtual ~Cursor(); ═══ 1.26. IOutOfMemory ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IOutOfMemory ═══ IException │ IResourceExhausted │ IOutOfMemory Inherited by none. ═══ Class Description - IOutOfMemory ═══ iexcbase.hpp Objects of the IOutOfMemory class represent an exception. The User Interface Class Library's new_handler function creates an object of the IOutOfMemory class when heap memory is exhausted. ═══ Public Functions - IOutOfMemory ═══ Constructors IOutOfMemory Exception Type name Inherited Members IResourceExhausted name IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IOutOfMemory - Constructors ═══ You can construct objects of this class. ═══ IOutOfMemory - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IOutOfMemory ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.26.1. IOutOfMemory::IOutOfMemory ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IOutOfMemory( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.26.2. IOutOfMemory::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.27. IOutOfSystemResource ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IOutOfSystemResource ═══ IException │ IResourceExhausted │ IOutOfSystemResource Inherited by none. ═══ Class Description - IOutOfSystemResource ═══ iexcbase.hpp Objects of the IOutOfSystemResource class represent an exception. When a member function makes an operating system resource request that the system cannot satisfy, the member function creates and throws an object of the IOutOfSystemResource class. ═══ Public Functions - IOutOfSystemResource ═══ Constructors IOutOfSystemResource Exception Type name Inherited Members IResourceExhausted name IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IOutOfSystemResource - Constructors ═══ You can construct objects of this class. ═══ IOutOfSystemResource - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IOutOfSystemResource ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.27.1. IOutOfSystemResource::IOutOfSystemResource ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IOutOfSystemResource( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.27.2. IOutOfSystemResource::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.28. IOutOfWindowResource ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IOutOfWindowResource ═══ IException │ IResourceExhausted │ IOutOfWindowResource Inherited by none. ═══ Class Description - IOutOfWindowResource ═══ iexcbase.hpp Objects of the IOutOfWindowResource class represent an exception. When a member function makes a presentation (window) system resource request that the system cannot satisfy, the member function creates and throws an object of the IOutOfWindowResource class. ═══ Public Functions - IOutOfWindowResource ═══ Constructors IOutOfWindowResource Exception Type name Inherited Members IResourceExhausted name IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IOutOfWindowResource - Constructors ═══ You can construct objects of this class. ═══ IOutOfWindowResource - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IOutOfWindowResource ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.28.1. IOutOfWindowResource::IOutOfWindowResource ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IOutOfWindowResource( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.28.2. IOutOfWindowResource::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.29. IPair ═══ Description Derivation Constructors Public Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IPair ═══ IBase │ IPair Inherited by: IPoint IRange ISize ═══ Class Description - IPair ═══ ipoint.hpp Objects of the IPair class are generic ordered pairs of coordinates. The class serves as the base for the following specific ordered pair classes: IPoint ISize IRange This class provides basic utilities to get and set the two coordinate values. In addition, it provides a full set of comparison and mathematical operators to manipulate ordered pairs. ═══ Public Functions - IPair ═══ Comparison Operators operator != operator < operator <= operator == operator > operator >= Constructors IPair Conversions asDebugInfo asString operator - Coordinates coord1 coord2 setCoord1 setCoord2 Manipulation operator %= operator *= operator += operator -= operator /= scaleBy scaledBy Minimum and Maximum maximum minimum Miscellaneous distanceFrom dotProduct transpose Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IPair - Comparison Operators ═══ Use these members to compare one IPair object to another. ═══ IPair - Constructors ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IPair objects. ═══ IPair - Conversions ═══ Use these members to return an IPair object in a different form. ═══ IPair - Coordinates ═══ Use these members to query and change the ordered pair of integers in an IPair object. ═══ IPair - Displaying ═══ Use this member to write ordered pairs to an ostream object. ═══ IPair - Manipulation ═══ Use these members to alter the coordinate values of an IPair object. This includes both member and non-member arithmetic operators and members to scale the value of an IPair object. ═══ IPair - Minimum and Maximum ═══ Use these members to determine the smaller or larger of two IPair objects. ═══ IPair - Miscellaneous ═══ These members are additional, unrelated members of the IPair class. ═══ Protected Data - IPair ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.29.1. IPair::asDebugInfo ═══ Converts the ordered pair to an IString containing a diagnostic representation of the object. public: IString asDebugInfo() const; ═══ 1.29.2. IPair::asString ═══ Converts the ordered pair (a, b) to an IString("(a, b)" ). public: IString asString() const; ═══ 1.29.3. IPair::coord1 ═══ Obtains the value of the first coordinate. public: Coord coord1() const; ═══ 1.29.4. IPair::coord2 ═══ Obtains the value of the second coordinate. public: Coord coord2() const; ═══ 1.29.5. IPair::distanceFrom ═══ Returns the distance from some other ordered pair. public: double distanceFrom(const IPair& aPair) const; ═══ 1.29.6. IPair::dotProduct ═══ Returns the dot product with another ordered pair. public: long dotProduct(const IPair& aPair) const; ═══ 1.29.7. IPair::IPair ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IPair objects. Overload 1 public: IPair(Coord init); Overload 2 public: IPair(); Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp Overload 3 public: IPair(Coord coord1, Coord coord2); Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Graphics Sample: 2d-draw.cpp Direct Manipulation Sample 4: dmsamp4.cpp ═══ 1.29.8. IPair::maximum ═══ Returns an ordered pair whose coordinates are the maximum of the corresponding coordinates of the IPair and the specified IPair. public: IPair maximum(const IPair& aPair) const; Used in sample: Multimedia MMREMOTE Sample: mmremote.cpp ═══ 1.29.9. IPair::minimum ═══ Returns an ordered pair whose coordinates are the minimum of the corresponding coordinates of the IPair and the specified IPair. public: IPair minimum(const IPair& aPair) const; ═══ 1.29.10. IPair::operator != ═══ True if either coordinate differs. public: Boolean operator !=(const IPair& aPair) const; ═══ 1.29.11. IPair::operator %= ═══ Replaces the coordinates with the remainder when divided by those of the following specified parameter: aPair The library performs the remainder function between the corresponding coordinates, coord1 with coord1 of aPair and coord2 with coord2. divisor The library performs the remainder function between each coordinate and the divisor. Overload 1 public: IPair& operator %=(const IPair& aPair); Overload 2 public: IPair& operator %=(long divisor); ═══ 1.29.12. IPair::operator *= ═══ Multiplies the coordinates by those of the specified parameter: aPair The library performs the product function between the corresponding coordinates, coord1 with coord1 of aPair and coord2 with coord2. multiplier The library perform the product function between each coordinate and the multiplier. Overload 1 public: IPair& operator *=(const IPair& aPair); Overload 2 public: IPair& operator *=(double multiplier); ═══ 1.29.13. IPair::operator += ═══ Adds the coordinates of the specified aPair to the coordinates of an ordered pair. public: IPair& operator +=(const IPair& aPair); Used in sample: Lancelot - A Valiant Example: ltimec.cpp ═══ 1.29.14. IPair::operator - ═══ Returns an ordered pair whose coordinates are the difference between the corresponding coordinates of pair1 and pair2. When you use the unary format, it returns an ordered pair with negated coordinates. public: IPair operator -() const; ═══ 1.29.15. IPair::operator -= ═══ Subtracts the coordinates specified in aPair from the IPair coordinates. public: IPair& operator -=(const IPair& aPair); ═══ 1.29.16. IPair::operator /= ═══ Divides the coordinates by those of the second specified parameter: aPair The library performs the quotient function between the corresponding coordinates, coord1 with coord1 of aPair and coord2 with coord2. divisor The library performs the product function between each coordinate and the divisor. Overload 1 public: IPair& operator /=(double divisor); Overload 2 public: IPair& operator /=(const IPair& aPair); ═══ 1.29.17. IPair::operator < ═══ True if both coordinates are less than those of the specified aPair. public: Boolean operator <(const IPair& aPair) const; ═══ 1.29.18. IPair::operator <= ═══ True if both coordinates are less than or equal. public: Boolean operator <=(const IPair& aPair) const; ═══ 1.29.19. IPair::operator == ═══ True if both coordinates match those of the specified aPair. public: Boolean operator ==(const IPair& aPair) const; ═══ 1.29.20. IPair::operator > ═══ True if both coordinates are greater than those of the specified aPair. public: Boolean operator >(const IPair& aPair) const; ═══ 1.29.21. IPair::operator >= ═══ True if both coordinates are greater than or equal. public: Boolean operator >=(const IPair& aPair) const; ═══ 1.29.22. IPair::scaleBy ═══ Scales the X-coordinate by xFactor, the Y-coordinate by yFactor. public: IPair& scaleBy(double xFactor, double yFactor); ═══ 1.29.23. IPair::scaledBy ═══ Same as IPair::scaleBy, but returns a new IPair, leaving the original unmodified. public: IPair scaledBy(double xFactor, double yFactor) const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp ═══ 1.29.24. IPair::setCoord1 ═══ Sets the value of the first coordinate. public: IPair& setCoord1(Coord coord1); ═══ 1.29.25. IPair::setCoord2 ═══ Sets the value of the second coordinate. public: IPair& setCoord2(Coord coord2); ═══ 1.29.26. IPair::transpose ═══ Swaps the coordinates of the ordered pair. The friend version of this function returns a new pair with transposed coordinates. public: IPair& transpose(); ═══ Nested Types - IPair ═══ Type Definitions Coord ═══ Type Definition - IPair::Coord ═══ typedef long Coord; Type of the coordinate values (long integer). ═══ 1.30. IPoint ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IPoint ═══ IBase │ IPair │ IPoint Inherited by none. ═══ Class Description - IPoint ═══ ipoint.hpp Objects of the IPoint class represent points in two-dimensional space. In addition to all the functions inherited from its base class, IPair, the IPoint class provides additional functions. Presentation Manager Information You can also construct objects of this class from a Presentation Manager Toolkit POINTL structure. ═══ Public Functions - IPoint ═══ Constructors IPoint Conversions asPOINTL Coordinates setX setY x y Inherited Members IPair asDebugInfo asString coord1 coord2 distanceFrom dotProduct maximum minimum operator != operator %= operator *= operator += operator - operator -= operator /= operator < operator <= operator == operator > operator >= scaleBy scaledBy setCoord1 setCoord2 transpose IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IPoint - Constructors ═══ You can create, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IPoint objects. ═══ IPoint - Conversions ═══ Use these members to return an IPoint object in a different form. ═══ IPoint - Coordinates ═══ Use these members to query and change the x and y coordinates of an IPoint object. ═══ Protected Data - IPoint ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.30.1. IPoint::asPOINTL ═══ Renders the point as a Presentation Manager Toolkit POINTL structure. public: struct _POINTL asPOINTL() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp ═══ 1.30.2. IPoint::IPoint ═══ You can create, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IPoint objects. Overload 1 public: IPoint(const struct _POINTL& ptl); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Overload 2 public: IPoint(); Used in samples: 2D Bitmap Sample: 2d-bmap.cpp 2D Graphics Sample: 2d-draw.cpp Lancelot - A Valiant Example: ltimepie.cpp Overload 3 public: IPoint(const IPair& pair); Overload 4 public: IPoint(Coord x, Coord y); Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: ahellow6.cpp Tool Bar Sample 1: tbar1.cpp Tool Bar Sample 2: tbar2.cpp 2D Graphics Sample: 2d-draw.cpp ═══ 1.30.3. IPoint::setX ═══ Sets the point's X-coordinate. public: IPoint& setX(Coord X); Used in sample: 2D Graphics Sample: 2d-draw.cpp ═══ 1.30.4. IPoint::setY ═══ Sets the point's Y-coordinate. public: IPoint& setY(Coord Y); Used in sample: 2D Graphics Sample: 2d-draw.cpp ═══ 1.30.5. IPoint::x ═══ Returns the point's X-coordinate. public: Coord x() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp Lancelot - A Valiant Example: lmainwin.cpp ═══ 1.30.6. IPoint::y ═══ Returns the point's Y-coordinate. public: Coord y() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp Lancelot - A Valiant Example: lmainwin.cpp ═══ 1.31. IPointArray ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IPointArray ═══ IBase │ IPointArray Inherited by none. ═══ Class Description - IPointArray ═══ iptarray.hpp The IPointArray class is used to represent an array of IPoint objects. ═══ Public Functions - IPointArray ═══ Comparisons operator != operator == Constructors IPointArray operator = ~IPointArray Data Access add insert operator [] remove resize reverse reversed size Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IPointArray - Comparisons ═══ Use these members to compare two point arrays. ═══ IPointArray - Constructors ═══ You can construct, copy, and assign objects of this class. ═══ IPointArray - Data Access ═══ Use these members to access attributes of objects of this class. ═══ Protected Data - IPointArray ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.31.1. IPointArray::add ═══ Adds a point to the end of the array. public: IPointArray& add(const IPoint& point); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.2. IPointArray::insert ═══ Inserts a point before the index specified. public: IPointArray& insert( unsigned long index, const IPoint& point); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.3. IPointArray::IPointArray ═══ You can construct, copy, and assign objects of this class. Overload 1 public: IPointArray(const IPointArray& pointArray); Use this function to construct a IPointArray object from an existing IPointArray object. Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Overload 2 public: IPointArray( unsigned long dimension = 0, const IPoint* array = 0); Use this function to construct a IPointArray object from two optional arguments. The first argument specifies the length of the array and the second argument is a pointer to an array of IPoint objects. The array of IPoints are used to initialize the IPointArray object. If a pointer to an array of IPoint objects is specified, it is assumed that the IPoint array has at least as many elements as the array dimension specified. Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp ═══ 1.31.4. IPointArray::operator != ═══ Returns true if the arrays are not the same length or the points are not identical or both. public: operator !=(const IPointArray& pointArray) const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.5. IPointArray::operator = ═══ public: IPointArray& operator =(const IPointArray& pointArray); Use this function to assign one IPointArray object to another. The target IPointArray object is grown or shrunk to the size of the source IPointArray object. Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.6. IPointArray::operator == ═══ Returns true if the arrays are the same length and have identical points. public: Boolean operator ==(const IPointArray& pointArray) const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.7. IPointArray::operator [] ═══ Returns a reference to the point at the specified index. Overload 1 public: IPoint& operator [](unsigned long index); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Overload 2 public: const IPoint& operator [](unsigned long index) const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.8. IPointArray::remove ═══ Removes a point at the specified index. public: IPointArray& remove(unsigned long index); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.9. IPointArray::resize ═══ Increases or decreases the size of the array. New points are initialized to 0,0. public: IPointArray& resize(unsigned long newsize); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.10. IPointArray::reverse ═══ Reverses the elements in the array. public: IPointArray& reverse(); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.11. IPointArray::reversed ═══ Returns a copy of the point array with its elements reversed. public: IPointArray reversed() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.12. IPointArray::size ═══ Returns the dimension of the array. public: unsigned long size() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.31.13. IPointArray::~IPointArray ═══ public: ~IPointArray(); Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.32. IRange ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IRange ═══ IBase │ IPair │ IRange Inherited by none. ═══ Class Description - IRange ═══ ipoint.hpp Objects of the IRange class represent a range of IPair::Coord values between a specified lower and upper bound (inclusive). ═══ Public Functions - IRange ═══ Constructors IRange Coordinates lowerBound setLowerBound setUpperBound upperBound Testing includes Inherited Members IPair asDebugInfo asString coord1 coord2 distanceFrom dotProduct maximum minimum operator != operator %= operator *= operator += operator - operator -= operator /= operator < operator <= operator == operator > operator >= scaleBy scaledBy setCoord1 setCoord2 transpose IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IRange - Constructors ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IRange objects. ═══ IRange - Coordinates ═══ Use these members to query and change the ordered pair of integers in an IRange object. ═══ IRange - Testing ═══ Use these members to test coordinate values. ═══ Protected Data - IRange ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.32.1. IRange::includes ═══ Returns true if the range contains the specified coordinate value. public: Boolean includes(Coord aValue) const; ═══ 1.32.2. IRange::IRange ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign IRange objects. Overload 1 public: IRange(Coord lower, Coord upper); Used in samples: Magnify Sample: magnify.cpp Multimedia MMSTEREO Sample: mltamp.cpp Lancelot - A Valiant Example: lskill.cpp Lancelot - A Valiant Example: ltimec.cpp Overload 2 public: IRange(); Overload 3 public: IRange(const IPair& aPair); ═══ 1.32.3. IRange::lowerBound ═══ Returns the lower bound of the range. public: Coord lowerBound() const; ═══ 1.32.4. IRange::setLowerBound ═══ Sets the lower bound of the range. public: IRange& setLowerBound(Coord lower); ═══ 1.32.5. IRange::setUpperBound ═══ Sets the upper bound of the range. public: IRange& setUpperBound(Coord upper); ═══ 1.32.6. IRange::upperBound ═══ Returns the upper bound of the range. public: Coord upperBound() const; ═══ 1.33. IRectangle ═══ Description Derivation Constructors Public Functions Protected Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IRectangle ═══ IBase │ IRectangle Inherited by none. ═══ Class Description - IRectangle ═══ irect.hpp Objects of the IRectangle class represent a rectangular area defined by two points that form opposite corners of the rectangle. These two points are referred to as the minimum and maximum points. IRectangle objects are designed to be usable independently of the coordinate system in use. The minimum, or origin, is defined as the point with the lowest coordinate values. Therefore, in a coordinate space where 0,0 is the upper left and increasing a point's coordinate value moves it to the right and down, the minimum point of an IRectangle will be the top left corner and the maximum corner the lower right corner. Conversely, in a coordinate space where 0,0 is the lower left corner and increasing a point's coordinate value moves it to the right and up, the minimum corner of an IRectangle will be the lower left, and the maximum corner the top right. IRectangle provides some member functions which use the terms "right", "left", "top", and "bottom". These are synonyms for the functions defined in terms of minimum and maximum corners. The directional orientation for the right/left/top/bottom functions is correct for a coordinate space where 0,0 is the lower left corner. For other coordinate systems, left and bottom are the sides of the rectangle with the lowest coordinate value, and top and right the sides with the highest. Mathematically, a rectangle includes all the points on the lines that intersect its minimum corner. It does not include the points that lie on its edges that do not intersect the origin. This is important when you are doing detailed graphics work. For example, a rectangle specified as having a minimum of 0,0 and maximum of 10,20 will include the points 0,0 though 0,19 but will not include 0,20. Similarly, the points 1,0 through 9,0 are contained but 10,0 is not. Various graphics and windowing classes, as well as their member functions, use rectangles. Presentation Manager Information You can also construct objects of this class by providing a Presentation Manager Toolkit RECTL structure. ═══ Public Functions - IRectangle ═══ Comparisons operator != operator == Constructors IRectangle Conversions asDebugInfo asRECTL asString Dimensions area height maxX maxY minX minY size width Manipulation centerAt centeredAt expandBy expandedBy moveBy movedBy movedTo moveTo scaleBy scaledBy shrinkBy shrunkBy sizeBy sizedBy sizedTo sizeTo Manipulation Operators operator & operator &= operator | operator |= Points centerXCenterY centerXMaxY centerXMinY maxXCenterY maxXMaxY maxXMinY minXCenterY minXMaxY minXMinY Synonyms bottom bottomCenter bottomLeft bottomRight center left leftCenter right rightCenter top topCenter topLeft topRight Testing contains intersects Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IRectangle - Comparisons ═══ Use these members to compare two rectangles for equality or inequality. ═══ IRectangle - Constructors ═══ You can construct, copy, and assign objects of this class. Note: The User Interface Class Library constructs rectangles by taking the two points that are given (or implied) as opposite corners. The minimum point, or origin, is set to be the lesser of the two points. This ensures that internally the origin and corner points always are such that the origin is less than or equal to the corner. ═══ IRectangle - Conversions ═══ Use these members to convert a rectangle into various formats. ═══ IRectangle - Dimensions ═══ Use these members to obtain information about a rectangle's size. ═══ IRectangle - Displaying ═══ Use these members to write a rectangle to a stream. ═══ IRectangle - Implementation ═══ These members are used internally to implement the class. ═══ IRectangle - Manipulation ═══ Use these members to modify the rectangle, changing its size, proportions, or location. ═══ IRectangle - Manipulation Operators ═══ Use these members to find a rectangle's union and intersection with another rectangle. ═══ IRectangle - Points ═══ Use these members to access points on or within the rectangle. You can query any of nine points on a rectangle's perimeter or its center by using these members. ═══ IRectangle - Synonyms ═══ Use these members when you are working in a coordinate space where 0,0 is the lower-left corner. In this case the right/left/top/bottom orientation is correct. You can still use these members in other coordinate systems, but left and bottom are the sides of the rectangle with the lowest coordinate value, and top and right are the sides with the highest. The following table lists the members and synonyms defined for them: Function Synonym minXMinY bottomLeft minXCenterY leftCenter minXMaxY topLeft centerXMinY bottomCenter centerXCenterY center centerXMaxY topCenter maxXMinY bottomRight maxXCenterY rightCenter maxXMaxY topRight minX left minY bottom maxX right maxY top ═══ IRectangle - Testing ═══ Use these members to test various attributes of a rectangle. ═══ Protected Functions - IRectangle ═══ Implementation validate ═══ Protected Data - IRectangle ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.33.1. IRectangle::area ═══ Returns the area of the rectangle. The area is determined by multiplying the width of the rectangle by the height. For example, a rectangle defined from IPoint(1,1), IPoint(10,20) would have an area of 9*19, or 171. public: Coord area() const; ═══ 1.33.2. IRectangle::asDebugInfo ═══ Renders the rectangle as a diagnostic representation. public: IString asDebugInfo() const; ═══ 1.33.3. IRectangle::asRECTL ═══ Converts the rectangle into a system dependent structure. public: struct _RECTL asRECTL() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Presentation Manager: Renders the rectangle as a Presentation Manager Toolkit RECTL structure. ═══ 1.33.4. IRectangle::asString ═══ Renders the rectangle as an IString("IRectangle(x1,y1,x2,y2)"). public: IString asString() const; ═══ 1.33.5. IRectangle::bottom ═══ Returns the Y-coordinate of the horizontal line that forms the bottom of the rectangle. This is an alias for IRectangle::minY. public: Coord bottom() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp Magnify Sample: magnify.cpp Direct Manipulation Sample 2: dmsamp2.cpp Lancelot - A Valiant Example: lgoodies.cpp Lancelot - A Valiant Example: ltimepie.cpp ═══ 1.33.6. IRectangle::bottomCenter ═══ Returns the X- and Y-coordinates of the bottom-center point of the rectangle. This is an alias for IRectangle::centerXMinY. public: IPoint bottomCenter() const; ═══ 1.33.7. IRectangle::bottomLeft ═══ Returns the X- and Y-coordinates of the bottom-left corner of the rectangle This is an alias for IRectangle::minXMinY. public: IPoint bottomLeft() const; Used in samples: Hello World Sample - Version 4: adialog4.cpp Hello World Sample - Version 5: adialog5.cpp Hello World Sample - Version 6: adialog6.cpp 2D Graphics Sample: 2d-menu.cpp BIGCPP Sample: bigcpp.cpp ═══ 1.33.8. IRectangle::bottomRight ═══ Returns the X- and Y-coordinates of the bottom-right corner of the rectangle. This is an alias for IRectangle::maxXMinY. public: IPoint bottomRight() const; Used in sample: BIGCPP Sample: bigcpp.cpp ═══ 1.33.9. IRectangle::center ═══ Returns the X- and Y-coordinates of the center point of the rectangle. This is an alias for IRectangle::centerXCenterY. public: IPoint center() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp Lancelot - A Valiant Example: lgoodies.cpp ═══ 1.33.10. IRectangle::centerAt ═══ Moves the rectangle so that its center is at the specified point. public: IRectangle& centerAt(const IPoint& point); Used in samples: 2D Graphics Sample: 2d-draw.cpp Magnify Sample: magnify.cpp Lancelot - A Valiant Example: lgoodies.cpp ═══ 1.33.11. IRectangle::centeredAt ═══ Same as IRectangle::centerAt, but returns a new rectangle, leaving the original unmodified. public: IRectangle centeredAt(const IPoint& point) const; ═══ 1.33.12. IRectangle::centerXCenterY ═══ Returns the X- and Y-coordinates of the center point of the rectangle. public: IPoint centerXCenterY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.13. IRectangle::centerXMaxY ═══ Returns the X- and Y-coordinates of the center point of the horizontal line opposite the origin of the rectangle. public: IPoint centerXMaxY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.14. IRectangle::centerXMinY ═══ Returns the X- and Y-coordinates of the center point of the horizontal line passing through the origin of the rectangle. public: IPoint centerXMinY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.15. IRectangle::contains ═══ If the rectangle contains the specified point or rectangle, true is returned. A point is contained by a rectangle if its coordinates are greater than or equal to the minimum point of the rectangle and less than the maximum point. A rectangle is contained within another rectangle if its minimum point is greater than or equal to the containing rectangle's minimum point and its maximum point is less than or equal to the containing rectangle's maximum point. Overload 1 public: Boolean contains(const IRectangle& rectangle) const; Overload 2 public: Boolean contains(const IPoint& point) const; ═══ 1.33.16. IRectangle::expandBy ═══ Moves the corners of the rectangle outward from the center by the specified amount. The specified amount can be either a scalar (long integer) or a point. Overload 1 public: IRectangle& expandBy(const IPair& pair); Overload 2 public: IRectangle& expandBy(Coord coord); Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp ═══ 1.33.17. IRectangle::expandedBy ═══ Same as IRectangle::expandBy, but returns a new rectangle, leaving the original unmodified. Overload 1 public: IRectangle expandedBy(const IPair& pair) const; Overload 2 public: IRectangle expandedBy(Coord coord) const; ═══ 1.33.18. IRectangle::height ═══ Returns the height of the rectangle. The height is determined by subtracting the y coordinate of the minimum point from the y coordinate of the maximum point. public: Coord height() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp Tool Bar Sample 2: tbar2.cpp 2D Graphics Sample: 2d-menu.cpp Direct Manipulation Sample 2: dmsamp2.cpp ═══ 1.33.19. IRectangle::intersects ═══ If the rectangle and specified rectangle overlap, true is returned. public: Boolean intersects(const IRectangle& rectangle) const; ═══ 1.33.20. IRectangle::IRectangle ═══ You can construct, copy, and assign objects of this class. Note: The User Interface Class Library constructs rectangles by taking the two points that are given (or implied) as opposite corners. The minimum point, or origin, is set to be the lesser of the two points. This ensures that internally the origin and corner points always are such that the origin is less than or equal to the corner. Overload 1 public: IRectangle(Coord width, Coord height); Constructs a rectangle of the specified size. The size is specified as width The width of the rectangle. height The height of the rectangle. Overload 2 public: IRectangle(); Constructs a rectangle at (0,0),(0,0). Used in samples: Hello World Sample - Version 5: ahellow5.cpp Hello World Sample - Version 6: ahellow6.cpp List Box Sample: alistbox.cpp 2D Bitmap Sample: 2d-bmap.cpp Message Box Sample: msgbox.cpp Overload 3 public: IRectangle(const IPoint& point1, const IPoint& point2); Constructs a rectangle from two points at opposite corners. Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp Direct Manipulation Sample 2: dmsamp2.cpp Lancelot - A Valiant Example: lmainwin.cpp Overload 4 public: IRectangle(const IPoint& point, const ISize& size); Creates a rectangle from a point and size. The maximum point is calculated by adding the width of the size to the x coordinate of the given point and adding the height of the size to the y coordinate of the given point. Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Bitmap Sample: 2d-bmap.cpp Tool Bar Sample 1: tbar1.cpp Tool Bar Sample 2: tbar2.cpp Overload 5 public: IRectangle( Coord point1X, Coord point1Y, Coord point2X, Coord point2Y); Constructs a rectangle from four values representing coordinates of the corners. point1X The X coordinate of point 1. point1Y The Y coordinate of point 1. point2X The X coordinate of point 2. point2Y The Y coordinate of point 2. Used in samples: Hello World Sample - Version 4: adialog4.cpp Hello World Sample - Version 5: adialog5.cpp Hello World Sample - Version 6: adialog6.cpp Magnify Sample: magnify.cpp Multimedia MMSTEREO Sample: mmstereo.cpp Overload 6 public: IRectangle(const struct _RECTL& rectl); Constructs a rectangle from a PM toolkit RECTL structure. Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ Overload 8 public: IRectangle(const IPair& pair); Constructs a rectangle with corners at 0,0 and the specified location. The lower of aPair and 0,0 will be the origin of the rectangle. ═══ 1.33.21. IRectangle::left ═══ Returns the X-coordinate of the vertical line that forms the left side of the rectangle. This is an alias for IRectangle::minX. public: Coord left() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp Magnify Sample: magnify.cpp Direct Manipulation Sample 2: dmsamp2.cpp Lancelot - A Valiant Example: lmainwin.cpp ═══ 1.33.22. IRectangle::leftCenter ═══ Returns the X- and Y-coordinates of the left-center point of the rectangle. This is an alias for IRectangle::minXCenterY. public: IPoint leftCenter() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Graphics Sample: 2d-menu.cpp ═══ 1.33.23. IRectangle::maxX ═══ Returns the X-coordinate of the vertical line that is opposite the origin of the rectangle. public: Coord maxX() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.24. IRectangle::maxXCenterY ═══ Returns the X- and Y-coordinates of the center point of the vertical line opposite the origin of the rectangle. public: IPoint maxXCenterY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.25. IRectangle::maxXMaxY ═══ Returns the X- and Y-coordinates of the corner of the rectangle opposite the origin. public: IPoint maxXMaxY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.26. IRectangle::maxXMinY ═══ Returns the X- and Y-coordinates of the corner of the rectangle at the other end of the horizontal line passing though the origin. public: IPoint maxXMinY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.27. IRectangle::maxY ═══ Returns the Y-coordinate of the horizontal line opposite the origin. public: Coord maxY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.28. IRectangle::minX ═══ Returns the X-coordinate of the vertical line that passes though the origin. public: Coord minX() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.29. IRectangle::minXCenterY ═══ Returns the X- and Y-coordinates of the center of the vertical line that passes through the origin. public: IPoint minXCenterY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.30. IRectangle::minXMaxY ═══ Returns the X- and Y-coordinates of the corner of the rectangle at the other end of the vertical line passing though the origin. public: IPoint minXMaxY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.31. IRectangle::minXMinY ═══ Returns the X- and Y-coordinates of the origin corner of the rectangle. public: IPoint minXMinY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.32. IRectangle::minY ═══ Returns the Y-coordinate of the horizontal line that passes though the origin of the rectangle. public: Coord minY() const; Platform Support ┌────────────┬────────────┐ │PM │MOTIF │ ├────────────┼────────────┤ │Yes │No │ └────────────┴────────────┘ ═══ 1.33.33. IRectangle::moveBy ═══ Moves the rectangle by the amount specified by aPair. public: IRectangle& moveBy(const IPair& pair); Used in samples: Hello World Sample - Version 4: adialog4.cpp Hello World Sample - Version 5: adialog5.cpp Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: adialog6.cpp Hello World Sample - Version 6: aearthw6.cpp ═══ 1.33.34. IRectangle::movedBy ═══ Same as IRectangle::moveBy, but returns a new rectangle, leaving the original unmodified. public: IRectangle movedBy(const IPair& pair) const; ═══ 1.33.35. IRectangle::movedTo ═══ Same as IRectangle::moveTo, but returns a new rectangle, leaving the original unmodified. public: IRectangle movedTo(const IPoint& point) const; ═══ 1.33.36. IRectangle::moveTo ═══ Moves the rectangle so that its origin corner is at the specified point. public: IRectangle& moveTo(const IPoint& point); Used in samples: Tool Bar Sample 2: tbar2.cpp 2D Graphics Sample: 2d-draw.cpp Magnify Sample: magnify.cpp ═══ 1.33.37. IRectangle::operator != ═══ If the rectangles differ, true is returned. public: Boolean operator !=(const IRectangle& rectangle) const; ═══ 1.33.38. IRectangle::operator & ═══ Returns a rectangle representing the intersection of the specified rectangles. public: IRectangle operator &(const IRectangle& rectangle) const; ═══ 1.33.39. IRectangle::operator &= ═══ Resets the rectangle to its intersection with the specified rectangle. public: IRectangle& operator &=(const IRectangle& rectangle); ═══ 1.33.40. IRectangle::operator == ═══ If the two rectangles are identical, true is returned. Identity of rectangles means that the two defining points are the same. public: Boolean operator ==(const IRectangle& rectangle) const; ═══ 1.33.41. IRectangle::operator | ═══ Returns the rectangle representing the union of the specified rectangles. This is the smallest rectangle that encompasses both specified rectangles. public: IRectangle operator |(const IRectangle& rectangle) const; ═══ 1.33.42. IRectangle::operator |= ═══ Resets the rectangle to its union with the specified rectangle. public: IRectangle& operator |=(const IRectangle& rectangle); ═══ 1.33.43. IRectangle::right ═══ Returns the X-coordinate of the vertical line that forms the right side of the rectangle. This is an alias for IRectangle::maxX. public: Coord right() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp Magnify Sample: magnify.cpp Lancelot - A Valiant Example: lgoodies.cpp Lancelot - A Valiant Example: ltimepie.cpp ═══ 1.33.44. IRectangle::rightCenter ═══ Returns the X- and Y-coordinates of the right-center point of the rectangle. This is an alias for IRectangle::maxXCenterY. public: IPoint rightCenter() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Graphics Sample: 2d-menu.cpp ═══ 1.33.45. IRectangle::scaleBy ═══ Scales the rectangle by the specified amount. Scaling a rectangle multiplies its coordinates by the scale amount. Overload 1 public: IRectangle& scaleBy(double factor); Scales by a double value. Overload 2 public: IRectangle& scaleBy(const IPair& pair); Scales by a point specifying the amounts in the X- and Y-axis directions. Overload 3 public: IRectangle& scaleBy(Coord coord); Scales by a long integer value. Overload 4 public: IRectangle& scaleBy(double xfactor, double yfactor); Scales by a pair of doubles. The function uses the first double to scale in the X-axis direction, the second in the Y-axis direction. ═══ 1.33.46. IRectangle::scaledBy ═══ Same as IRectangle::scaleBy, but returns a new rectangle, leaving the original unmodified. Overload 1 public: IRectangle scaledBy(const IPair& pair) const; Overload 2 public: IRectangle scaledBy(Coord coord) const; Overload 3 public: IRectangle scaledBy(double factor) const; Overload 4 public: IRectangle scaledBy(double xfactor, double yfactor) const; ═══ 1.33.47. IRectangle::shrinkBy ═══ Moves the corners of the rectangle inward toward the center by the specified amount, either a scalar or a point. Note: shrinkBy(anAmount) is always equivalent to expandBy(- anAmount), and vice versa. Overload 1 public: IRectangle& shrinkBy(Coord coord); Used in samples: 2D Bitmap Sample: 2d-bmap.cpp BIGCPP Sample: bigcpp.cpp Overload 2 public: IRectangle& shrinkBy(const IPair& pair); ═══ 1.33.48. IRectangle::shrunkBy ═══ Same as IRectangle::shrinkBy, but returns a new rectangle, leaving the original unmodified. Overload 1 public: IRectangle shrunkBy(const IPair& pair) const; Overload 2 public: IRectangle shrunkBy(Coord coord) const; ═══ 1.33.49. IRectangle::size ═══ Returns the ISize(width, height). public: ISize size() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp 2D Graphics Sample: 2d-draw.cpp BIGCPP Sample: bigcpp.cpp ═══ 1.33.50. IRectangle::sizeBy ═══ Scales the rectangle by the specified value, leaving the rectangle at the same location because the bottom-left point remains fixed. Overload 1 public: IRectangle& sizeBy(double xfactor, double yfactor); Scales by two doubles specifying factors in the X-axis and Y-axis directions, respectively. Overload 2 public: IRectangle& sizeBy(const IPair& pair); Scales by a pair of integer scalars specifying different factors in the X-axis and Y-axis directions. Overload 3 public: IRectangle& sizeBy(Coord factor); Scales by the same integer factor in both the X-axis and Y-axis directions. Overload 4 public: IRectangle& sizeBy(double factor); Scales by the same double factor in both the X-axis and Y-axis directions. ═══ 1.33.51. IRectangle::sizedBy ═══ Same as IRectangle::sizeBy, but returns a new rectangle, leaving the original unmodified. Overload 1 public: IRectangle sizedBy(double factor) const; Overload 2 public: IRectangle sizedBy(const IPair& pair) const; Overload 3 public: IRectangle sizedBy(Coord factor) const; Overload 4 public: IRectangle sizedBy(double xfactor, double yfactor) const; ═══ 1.33.52. IRectangle::sizedTo ═══ Same as IRectangle::sizeTo, but returns a new rectangle, leaving the original unmodified. public: IRectangle sizedTo(const IPair& pair) const; ═══ 1.33.53. IRectangle::sizeTo ═══ Sizes the rectangle to the specified size. public: IRectangle& sizeTo(const IPair& pair); Used in samples: Tool Bar Sample 2: tbar2.cpp 2D Graphics Sample: 2d-draw.cpp ═══ 1.33.54. IRectangle::top ═══ Returns the Y-coordinate of the horizontal line that forms the top of the rectangle. This is an alias for IRectangle::maxY. public: Coord top() const; Used in samples: 2D Graphics Sample: 2d-draw.cpp Magnify Sample: magnify.cpp Lancelot - A Valiant Example: lmainwin.cpp Lancelot - A Valiant Example: ltimepie.cpp Lancelot - A Valiant Example: lperswin.cpp ═══ 1.33.55. IRectangle::topCenter ═══ Returns the X- and Y-coordinates of the top-center point of the rectangle. This is an alias for IRectangle::centerXMaxY. public: IPoint topCenter() const; Used in samples: Hello World Sample - Version 5: aearthw5.cpp Hello World Sample - Version 6: aearthw6.cpp ═══ 1.33.56. IRectangle::topLeft ═══ Returns the X- and Y-coordinates of the top-left corner of the rectangle. This is an alias for IRectangle::minXMaxY. public: IPoint topLeft() const; Used in sample: BIGCPP Sample: bigcpp.cpp ═══ 1.33.57. IRectangle::topRight ═══ Returns the X- and Y-coordinates of the top-right corner of the rectangle. This is an alias for IRectangle::maxXMaxY. public: IPoint topRight() const; Used in samples: 2D Graphics Sample: 2d-menu.cpp BIGCPP Sample: bigcpp.cpp ═══ 1.33.58. IRectangle::validate ═══ Corrects an invalid rectangle after creation, expansion, or intersection. protected: IRectangle& validate(); ═══ 1.33.59. IRectangle::width ═══ Returns the width of the rectangle. The width is determined by subtracting the x coordinate of the minimum point from the x coordinate of the maximum point. public: Coord width() const; Used in samples: Tool Bar Sample 2: tbar2.cpp Direct Manipulation Sample 2: dmsamp2.cpp ═══ Nested Types - IRectangle ═══ Type Definitions Coord ═══ Type Definition - IRectangle::Coord ═══ typedef IPair::Coord Coord; Type of the coordinate values; this must match the type of the coordinates supported by the IPair class. ═══ 1.34. IRefCounted ═══ Description Derivation Public Functions Protected Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IRefCounted ═══ IBase │ IVBase │ IRefCounted Inherited by: IDMItem IDMOperation IStringGeneratorFn IThreadFn ITimerFn ═══ Class Description - IRefCounted ═══ irefcnt.hpp The IRefCounted class is a public base class for any class that is reference counted. Such inheritance conveys the functional characteristics of maintaining a count of all references to the object and deferring destruction until all such references are destroyed. By necessity, you can only allocate objects of this class in free store. The library enforces this by making the destructor for this class protected. As a result, the library only allows IRefCounted::removeRef and derived class destructors to call IRefCounted::IRefCounted. Derived classes should make their destructors protected also. Typically, you use this class in conjunction with the corresponding IReference, where T is a derived class of IRefCounted. ═══ Public Functions - IRefCounted ═══ Reference Counting addRef removeRef useCount Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IRefCounted - Constructors ═══ These members are protected. ═══ IRefCounted - Reference Counting ═══ Use these members to manage the object's reference count. ═══ Protected Functions - IRefCounted ═══ Constructors IRefCounted ~IRefCounted ═══ Protected Data - IRefCounted ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.34.1. IRefCounted::addRef ═══ Adds a reference to the referred-to object. public: virtual void addRef(); ═══ 1.34.2. IRefCounted::IRefCounted ═══ These members are protected. protected: IRefCounted(); ═══ 1.34.3. IRefCounted::removeRef ═══ Removes a reference to the referred-to object. When the reference count goes to 0, this function deletes the referred-to object. public: virtual void removeRef(); ═══ 1.34.4. IRefCounted::useCount ═══ Returns the use count for the referred-to object. public: unsigned useCount() const; ═══ 1.34.5. IRefCounted::~IRefCounted ═══ protected: ~IRefCounted(); ═══ 1.35. IReference ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IReference ═══ IBase │ IReference Inherited by none. ═══ Class Description - IReference ═══ irefcnt.hpp The template class IReference is derived from classes that serve as references. Objects of such classes serve as smart pointers to objects of the referenced class. Creating objects of this class increments the use count of the referenced object. Destruction of the object causes the use count of the referenced object to be decremented. Typically, this class is referenced explicitly only as a public base class of the class that provides the additional capability of the reference class. For example: class Foo { .. }; class FooRef : public IReference { // Additional FooRef functions... }; The reference-counted class provided as the template argument is derived from the class IRefCounted. It must have the member functions IRefCounted::addRefand IRefCounted::removeRef with equivalent semantics. To construct an IReference, you must provide a pointer to an object of the referenced (reference-counted) class. All constructors of the real reference class (derived from IReference) must provide such a pointer. Otherwise, the reference class has no additional responsibilities. Note: 1. The semantics of such reference or referent classes can have subtle complexities. The reference or the referent might behave in an extraordinary fashion. 2. A class can also serve as a reference by having as a data member an IReference object. 3. All members of the IReference class are public in order to permit the usage described in item 2. Customization (Template Argument) IReference is a template class that is instantiated with the following template argument: T Specifies the name of the class of objects to which template class objects refer. ═══ Public Functions - IReference ═══ Constructors IReference operator = ~IReference Operators operator * operator -> operator T * Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IReference - Constructors ═══ You can construct, destruct, copy, and assign objects of this class. ═══ IReference - Operators ═══ Use these members to access the referenced object. Their effect is to make an IReference usable, similar to a normal pointer. ═══ Protected Data - IReference ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.35.1. IReference::IReference ═══ You can construct, destruct, copy, and assign objects of this class. Overload 1 public: IReference(const IReference < T >& source); You can construct objects of this class by using this copy constructor which the library provides to ensure that the reference counts for both the source and target referents are maintained properly. Overload 2 public: IReference(T* p = 0); You can construct objects of this class by using this primary constructor which accepts a pointer to an instance of the referenced class. This also serves as the default constructor (defaulting the pointer parameter to 0). ═══ 1.35.2. IReference::operator * ═══ Pointer de-reference operator that provides access to the referenced object. public: T& operator *() const; ═══ 1.35.3. IReference::operator -> ═══ Pointer operator that provides access to the referenced object. public: T* operator ->() const; ═══ 1.35.4. IReference::operator = ═══ The assignment operator. You can assign one IReference to another or you can assign a pointer to the referenced type. Overload 1 public: IReference < T >& operator =(T* p); Overload 2 public: IReference < T >& operator =( const IReference < T >& source); ═══ 1.35.5. IReference::operator T * ═══ Returns the referent. public: operator T *() const; ═══ 1.35.6. IReference::~IReference ═══ The destructor ensures that the referenced object is de-referenced. public: ~IReference(); ═══ 1.36. IResourceExhausted ═══ Description Derivation Constructors Public Functions Public Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IResourceExhausted ═══ IException │ IResourceExhausted Inherited by: IOutOfMemory IOutOfSystemResource IOutOfWindowResource ═══ Class Description - IResourceExhausted ═══ iexcbase.hpp Objects of the IResourceExhausted class represent an exception. When a member function makes a resource request of the operating system or the presentation system that it cannot satisfy, the member function creates and throws an object of the IResourceExhausted class or one of its derived classes. IResourceExhausted is the generic out-of-resource class. Member functions use IResourceExhausted whenever its derived classes, which are for specific out-of-resource cases, are not applicable. The derived classes for IResourceExhausted are: IOutOfMemory IOutOfSystemResource IOutOfWindowResource ═══ Public Functions - IResourceExhausted ═══ Constructors IResourceExhausted Exception Type name Inherited Members IException addLocation appendText assertParameter errorCodeGroup errorId isRecoverable locationAtIndex locationCount logExceptionData name setErrorCodeGroup setErrorId setSeverity setText setTraceFunction terminate text textCount ═══ IResourceExhausted - Constructors ═══ You can construct objects of this class. ═══ IResourceExhausted - Exception Type ═══ Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information. ═══ Public Data - IResourceExhausted ═══ Inherited Members IException baseLibrary CLibrary operatingSystem other presentationSystem ═══ 1.36.1. IResourceExhausted::IResourceExhausted ═══ You can create objects of this class by doing the following: Using the constructor. errorText The text describing this particular error. errorId The identifier you want to associate with this particular error. severity Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Using the macros discussed in IException. The User Interface Class Library provides these macros to make creating exceptions easier for you. public: IResourceExhausted( const char* errorText, unsigned long errorId, Severity severity = IException::unrecoverable); ═══ 1.36.2. IResourceExhausted::name ═══ Returns the name of the object's class. public: virtual const char* name() const; ═══ 1.37. ISize ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - ISize ═══ IBase │ IPair │ ISize Inherited by none. ═══ Class Description - ISize ═══ ipoint.hpp Objects of the ISize class use their coordinates to represent a rectangular size, in horizontal and vertical dimensions. Presentation Manager Information You can also construct objects of this class using: A Presentation Manager Toolkit SIZEL structure. A Presentation Manager Toolkit RECTL structure; in this case, the resulting ISize object represents the size of the RECTL. ═══ Public Functions - ISize ═══ Constructors ISize Conversions asSIZEL Coordinates height setHeight setWidth width Inherited Members IPair asDebugInfo asString coord1 coord2 distanceFrom dotProduct maximum minimum operator != operator %= operator *= operator += operator - operator -= operator /= operator < operator <= operator == operator > operator >= scaleBy scaledBy setCoord1 setCoord2 transpose IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ ISize - Constructors ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign ISize objects. ═══ ISize - Conversions ═══ Use these members to return an ISize object in a different form. ═══ ISize - Coordinates ═══ Use these members to query and change the ordered pair of integers in an ISize object. ═══ Protected Data - ISize ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.37.1. ISize::asSIZEL ═══ Returns the ISize as a Presentation Manager Toolkit SIZEL structure. public: SIZEL asSIZEL() const; ═══ 1.37.2. ISize::height ═══ Returns the height represented by the ISize object. public: Coord height() const; Used in samples: Hello World Sample - Version 4: ahellow4.cpp Hello World Sample - Version 5: ahellow5.cpp Hello World Sample - Version 6: ahellow6.cpp Tool Bar Sample 2: tbar2.cpp View Port Sample: avport.cpp ═══ 1.37.3. ISize::ISize ═══ You can construct, copy, and assign objects of this class. This class uses the compiler-generated copy constructor and assignment operator to copy and assign ISize objects. Overload 1 public: ISize(const IPair& pair); Overload 2 public: ISize(); Used in samples: Hello World Sample - Version 4: ahellow4.cpp Hello World Sample - Version 5: ahellow5.cpp Hello World Sample - Version 6: ahellow6.cpp 2D Bitmap Sample: 2d-bmap.cpp Multimedia MMREMOTE Sample: mmremote.cpp Overload 3 public: ISize(Coord width, Coord height); Used in samples: Hello World Sample - Version 1: ahellow1.cpp Hello World Sample - Version 2: ahellow2.cpp Hello World Sample - Version 3: ahellow3.cpp Hello World Sample - Version 4: ahellow4.cpp Hello World Sample - Version 5: ahellow5.cpp Overload 4 public: ISize(const SIZEL& sizl); Overload 5 public: ISize(const struct _RECTL& rcl); ═══ 1.37.4. ISize::setHeight ═══ Sets the size's height. public: ISize& setHeight(Coord cy); Used in samples: 2D Graphics Sample: 2d-menu.cpp Multimedia MMREMOTE Sample: mmremote.cpp Lancelot - A Valiant Example: ltimec.cpp ═══ 1.37.5. ISize::setWidth ═══ Sets the size's width. public: ISize& setWidth(Coord cx); Used in samples: 2D Graphics Sample: 2d-menu.cpp Multimedia MMREMOTE Sample: mmremote.cpp Lancelot - A Valiant Example: lgenl.cpp Lancelot - A Valiant Example: ltimec.cpp ═══ 1.37.6. ISize::width ═══ Returns the width represented by the ISize object. public: Coord width() const; Used in samples: Tool Bar Sample 2: tbar2.cpp View Port Sample: avport.cpp BIGCPP Sample: bigcpp.cpp Magnify Sample: magnify.cpp Multimedia MMREMOTE Sample: mmremote.cpp ═══ 1.38. IStandardNotifier ═══ Description Derivation Constructors Public Functions Protected Functions Public Data Protected Data Public Data includes Styles and Notification IDs if they exist. To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IStandardNotifier ═══ IBase │ IVBase │ INotifier │ IStandardNotifier Inherited by: IMMDevice IMMMasterAudio ═══ Class Description - IStandardNotifier ═══ istdntfy.hpp The IStandardNotifier class provides a direct implementation of the notification protocol in the INotifier class. You can implement a notification protocol in the following way: Derive a class from the IStandardNotifier class which inherits from INotifier for a direct implementation of the INotifier protocol Derive from the INotifier class and implement your own notification protocol Because IWindow inherits from and implements the INotifier protocol, IWindow provides a visual notification implementation. IStandardNotifier inherits from INotifier and can be used for any generic notifier, without the visual interface available in IWindow objects. You might want to derive your classes from IStandardNotifier if you are providing a nonvisual notifier. ═══ Public Functions - IStandardNotifier ═══ Constructors IStandardNotifier operator = ~IStandardNotifier Notification Members disableNotification enableNotification isEnabledForNotification Observer Notification notifyObservers Inherited Members INotifier disableNotification enableNotification isEnabledForNotification notifyObservers IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IStandardNotifier - Constructors ═══ You can construct, destruct, assign, and copy objects of this class. ═══ IStandardNotifier - Notification Event Descriptions ═══ These INotificationId strings are used for all notifications that an IPart provides to its observers. ═══ IStandardNotifier - Notification Members ═══ Use these members to affect the ability of a part to notify observers of events of interest. ═══ IStandardNotifier - Observer Addition and Removal ═══ Use these members to manage the collection of observers maintained by the notifier. ═══ IStandardNotifier - Observer Notification ═══ These members notify observers of a change in a notifier. ═══ Protected Functions - IStandardNotifier ═══ Observer Addition and Removal addObserver observerList removeAllObservers removeObserver Observer Notification notifyObservers Inherited Members INotifier addObserver notifyObservers observerList removeAllObservers removeObserver ═══ Public Data - IStandardNotifier ═══ Notification Event Descriptions deleteId ═══ Protected Data - IStandardNotifier ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.38.1. IStandardNotifier::addObserver ═══ Adds an observer to the object's list of observers. protected: virtual IStandardNotifier& addObserver( IObserver& observer, const IEventData& userData = IEventData ( 0 )); ═══ 1.38.2. IStandardNotifier::deleteId ═══ Notification identifier provided to observers when the notifier object is deleted. Note: IStandardNotifier sends this notification from its destructor. This means that the derived portions of the notifier have already been deleted. You should therefore not cast the pointer to the notifier data, to an object that is derived from IStandardNotifier. This operation is synchronous and therefore the pointer still points to a valid object. public: static INotificationId const deleteId; ═══ 1.38.3. IStandardNotifier::disableNotification ═══ Stops the object from sending notifications to registered observers. public: virtual IStandardNotifier& disableNotification(); ═══ 1.38.4. IStandardNotifier::enableNotification ═══ Starts the sending of notifications to observers. public: virtual IStandardNotifier& enableNotification( Boolean enable = true); ═══ 1.38.5. IStandardNotifier::isEnabledForNotification ═══ Returns true if an object is sending notifications to its observers. public: virtual Boolean isEnabledForNotification() const; ═══ 1.38.6. IStandardNotifier::IStandardNotifier ═══ You can construct, destruct, assign, and copy objects of this class. Overload 1 public: IStandardNotifier(const IStandardNotifier& copy); You can construct an IStandardNotifier object using a copy of an existing IStandardNotifier object. Overload 2 public: IStandardNotifier(); You can construct objects of this class using the default constructor that takes no arguments. ═══ 1.38.7. IStandardNotifier::notifyObservers ═══ Notifies all observers in an object's observer list. Note: A public and a protected version of notifyObservers are provided for convenience. The protected version does not require the caller to construct an INotificationEvent to call it. In this case, the construction of the INotificationEventobject occurs in the code of the protected notifyObservers function. Overload 1 public: virtual IStandardNotifier& notifyObservers( const INotificationEvent& anEvent); Overload 2 protected: virtual IStandardNotifier& notifyObservers( const INotificationId& nId); ═══ 1.38.8. IStandardNotifier::observerList ═══ Returns the list of IObservers. The list is created it if it does not exist. protected: virtual IObserverList& observerList() const; ═══ 1.38.9. IStandardNotifier::operator = ═══ Assigns the contents of one notifier object to another. Note: The observer list is not copied. public: IStandardNotifier& operator =( const IStandardNotifier& aStandardNotifier); ═══ 1.38.10. IStandardNotifier::removeAllObservers ═══ Removes all observers from the object's observer list. protected: virtual IStandardNotifier& removeAllObservers(); ═══ 1.38.11. IStandardNotifier::removeObserver ═══ Removes an observer from the objects's observer list. protected: virtual IStandardNotifier& removeObserver( IObserver& observer); ═══ 1.38.12. IStandardNotifier::~IStandardNotifier ═══ public: virtual ~IStandardNotifier(); ═══ 1.39. IString ═══ Description Derivation Constructors Public Functions Protected Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IString ═══ IBase │ IString Inherited by: I0String ═══ Class Description - IString ═══ istring.hpp Objects of the IString class are arrays of characters. These objects are functionally equivalent to objects of the class I0String with one major distinction: IStrings are indexed starting at 1 instead of 0. IString provides an operator char*. In order to access the actual string contained in an object of type IString, cast the assignment variable implicitly or explicitly. IStrings provide the following functions beyond that available from the standard C char* arrays and the STRING.H library functions: No restrictions on string contents. Thus, strings can contain NULL characters. Automatic conversion from and to numeric types. Automatic deletion of the string buffer when the IString is destroyed. Full support for the following: - All comparison operators - All bitwise operators - Concatenation using the more natural + operator. String data testing, such as for characters, digits, and hexadecimal digits. A full complement of the following: - String manipulation functions, such as center, left- and right-justification, stripping of leading and trailing characters, deleting substrings, and inserting strings - Corresponding string manipulation functions that return a new IString rather than modifying the receiver - String searching functions, such as byte index of string and last-byte index of string. Word manipulation, such as index of word and search for word phrase. Support for mixed strings that contain both single-byte character set (SBCS) and double-byte character set (DBCS) characters. When a program using IStrings is run on a DBCS system, the IString objects support DBCS characters within the string contents. The various IString search functions do not accidentally match an SBCS character with the second byte of a DBCS character that has the same value. Also, IString functions that modify IStrings, such as subString, remove, and translate, never separate the two bytes of a DBCS character. If one of the two bytes of a DBCS character is removed, the remaining byte is replaced with the appropriate pad character (if the function performing the change has one) or a blank. When working with IStrings that contain DBCS data, ensure that the contents are not altered in such a way as to corrupt the data. For example, the statement: aString[ n ] = 'x'; would be in error if the nth character of the IString was the first or second byte of a DBCS character. Note: Any function that reallocates an IString can throw an exception for out-of-range errors. These occur if you attempt to construct an IString with a length greater than UINT_MAX. IStrings are held in IBuffers which allocate the area for the character arrays using the C++ operator new. The only limitation for the size of an IString are the limitations imposed by the operating system. Motif Information DBCS is equivalent to Multiple-byte character set (MBCS). ═══ Public Functions - IString ═══ Binary Conversions b2c b2d b2x Character Conversions c2b c2d c2x Constructors IString ~IString Diagnostics asDebugInfo asString Editing center change copy insert leftJustify lowerCase overlayWith remove reverse rightJustify strip stripBlanks stripLeading stripLeadingBlanks stripTrailing stripTrailingBlanks translate upperCase Forward Searches indexOf indexOfAnyBut indexOfAnyOf occurrencesOf Hex Conversions x2b x2c x2d Manipulation operator & operator &= operator + operator += operator = operator ^ operator ^= operator | operator |= operator ~ NLS Testing includesDBCS includesMBCS includesSBCS isDBCS isMBCS isSBCS isValidDBCS isValidMBCS Numeric Conversions d2b d2c d2x Pattern Matching includes isAbbreviationFor isLike Queries charType length operator [] size subString Reverse Searches lastIndexOf lastIndexOfAnyBut lastIndexOfAnyOf Stream Input lineFrom Testing isAlphabetic isAlphanumeric isASCII isBinaryDigits isControl isDigits isGraphics isHexDigits isLowerCase isPrintable isPunctuation isUpperCase isWhiteSpace Type Conversions asDouble asInt asUnsigned operator char * operator signed char * operator unsigned char * Word Operations indexOfPhrase indexOfWord lengthOfWord numWords removeWords space word wordIndexOfPhrase words Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IString - Binary Conversions ═══ These members work if isBinaryDigits() == true; if not, they return a null string. The static members by the same name can be applied to a string to return the modified string without changing the argument string. ═══ IString - Bit Operations ═══ Use these members to implement various public members of this class requiring bitwise operations. ═══ IString - Character Conversions ═══ These members always work; they convert a string to binary, numeric or hexadecimal representation. The static members by the same name can be applied to a string to return the modified string without changing the argument string. These members are used much like the similar REXX functions. For example: aString.c2b(); // Changes aString. String binaryDigits = IString::c2b( aString ); // Leaves aString alone. ═══ IString - Comparisons ═══ All Boolean operators are defined for strings. The following members are overloaded so that IStrings can be compared to objects of type char*, as well as to other IStrings. ═══ IString - Constructors ═══ You can construct objects of this class in the following ways: Construct a NULL string. Construct a string with the ASCII representation of a given numeric value, supporting all flavors of integer and double. Construct a string with a copy of the specified character data, supporting ASCIIZ strings, characters, and IStrings. The character data passed is converted to its ASCII representation. Construct a string with contents that consist of copies of up to three buffers of arbitrary data (void*). Optionally, you only need to provide the length, in which case the IString contents are initialized to a specified pad character. The default character is a blank. These constructors can throw exceptions under the following conditions: Memory allocation errors Many factors dynamically allocate space and these allocation requests may fail. If so, the User Interface Class Library translates memory allocation errors into exceptions. Generally, such errors do not occur until you allocate an astronomical amount of storage. Out-of-range errors These occur if you attempt to construct an IString with a length greater than UINT_MAX. ═══ IString - Diagnostics ═══ These members provide IString diagnostic information for IString objects. Often, you use these members to write trace information when debugging. ═══ IString - Editing ═══ Use these members to edit a string. All return a reference to the modified receiver. Many that are length related, such as center and leftJustify, accept a pad character that defaults to a blank. In all cases, you can specify argument strings as either objects of the IString class or by using char*. Static members by the same name can be applied to an IString to obtain the modified IString without affecting the argument. For example: aString.change('\t', ' '); // Changes all tabs in aString to 3 blanks. IString s = IString::change( aString, '\t', ' ' ); // Leaves aString as is. ═══ IString - Forward Searches ═══ These members permit searching a string in various ways. You can specify an optional index that indicates the search start position. The default starts at the beginning of the string. ═══ IString - Hex Conversions ═══ These members work if isHexDigits() == true; if not, they return a null string. The static members by the same name can be applied to a string to return the modified string without changing the argument string. ═══ IString - Implementation ═══ Use these members to implement this class; specifically, they initialize or set the underlying IBuffer data. ═══ IString - Manipulation ═══ Use these members to manipulate a string's contents. All are overloaded so that standard C strings can be used efficiently without constructing an equivalent String first. ═══ IString - NLS Testing ═══ Use these members to test the characters that comprise a string. Basically, you use these members to determine if an IString contains only characters from a specific NLS character set (SBCS, MBCS, DBCS). ═══ IString - Numeric Conversions ═══ These members work if isDigits() == true; if not, they return a null string. The static members by the same name can be applied to a string to return the modified string without changing the argument string. ═══ IString - Pattern Matching ═══ Use these members to determine if an object of this class contains a given pattern of characters. ═══ IString - Queries ═══ Use these members to access general information about the string. ═══ IString - Reverse Searches ═══ These members permit searching the string in various ways. The lastIndexOf versions correspond to forward search indexOf members but start the search from the end of the string. These members return the index of the last character in the receiver IString that satisfies the search criteria. Also, they accept an optional argument that specifies where the search is to begin. The default is to start searching at the end of the string. Searching proceeds from right to left for these members. ═══ IString - Stream Input ═══ Use these members to read IStrings from standard C++ streams. ═══ IString - Testing ═══ Use these members to determine if an IString contains only characters from a predefined set. ═══ IString - Type Conversions ═══ Use these members to convert a string to various other data types. The types supported are the same set as are supported by the IString constructors. ═══ IString - Utility Data ═══ These protected static data members provide useful values for implementing IString. IString uses the various representation of null and zero for initialization and comparison purposes. ═══ IString - Word Operations ═══ These members operate on a string as a collection of words separated by whitespace characters. They find, remove, and count words or phrases. ═══ Protected Functions - IString ═══ Bit Operations applyBitOp Editing change insert overlayWith strip translate Forward Searches findPhrase indexOfWord occurrencesOf Implementation initBuffer setBuffer Queries buffer data defaultBuffer lengthOf Testing isAbbrevFor isLike ═══ Protected Data - IString ═══ Utility Data maxLong null nullBuffer zero Inherited Members IBase recoverable unrecoverable ═══ 1.39.1. IString::applyBitOp ═══ Implements the bitwise operators &, |, and ^. protected: IString& applyBitOp( const char* pArg, unsigned argLen, BitOperator op); ═══ 1.39.2. IString::asDebugInfo ═══ Returns information about the IString's internal representation that you can use for debugging. public: IString asDebugInfo() const; ═══ 1.39.3. IString::asDouble ═══ Returns, as a double, the number that the string represents. public: double asDouble() const; ═══ 1.39.4. IString::asInt ═══ Returns the number that the string represents as a long integer. Note: If an IString contains nonnumeric characters, this function returns the integer for the portion of the IString up to, but not including, the nonnumeric character. The rest of the IString, following the invalid character, is not returned. If an IString is larger than the maximum integer, this function returns the maximum integer, not the larger value. public: long asInt() const; Used in samples: Lancelot - A Valiant Example: lskill.cpp Lancelot - A Valiant Example: ltimec.cpp Lancelot - A Valiant Example: ltimepie.cpp ═══ 1.39.5. IString::asString ═══ Returns the string itself, so that IString supports this common IBaseprotocol. public: IString asString() const; ═══ 1.39.6. IString::asUnsigned ═══ Returns, as an unsigned long, the integer that the string represents. public: unsigned long asUnsigned() const; Used in samples: Container Clipboard Sample: clipbrd.cpp Direct Manipulation Sample 4: dmsamp4.cpp ═══ 1.39.7. IString::b2c ═══ Converts a string of binary digits to a normal string of characters. For example, this function changes 01 to \x01 and 00110011 to 3. Note: This function is not locale sensitive. Overload 1 public: static IString b2c(const IString& aString); Overload 2 public: IString& b2c(); ═══ 1.39.8. IString::b2d ═══ Converts a string of binary digits to a string of decimal digits. For example, this function changes 00011001 to 25 and 0001001000110100 to 4660. Overload 1 public: IString& b2d(); Overload 2 public: static IString b2d(const IString& aString); ═══ 1.39.9. IString::b2x ═══ Converts a string of binary digits to a string of hexadecimal digits. For example, this function changes 00011011 to 1b and 10001001000110100 to 11234. Overload 1 public: IString& b2x(); Overload 2 public: static IString b2x(const IString& aString); ═══ 1.39.10. IString::buffer ═══ Returns the address of the IBuffer referred to by this IString. protected: IBuffer* buffer() const; ═══ 1.39.11. IString::c2b ═══ Converts a normal string of characters to a string of binary digits. For example, this function changes "a" to 01100001 and 12 to 11000100110010. Note: This function is not locale-sensitive. Overload 1 public: static IString c2b(const IString& aString); Overload 2 public: IString& c2b(); ═══ 1.39.12. IString::c2d ═══ Converts a normal string of characters to a string of decimal digits. For example, this function changes "a" to 97 and "ab" to 24930. Note: This function is not locale sensitive. Overload 1 public: static IString c2d(const IString& aString); Overload 2 public: IString& c2d(); ═══ 1.39.13. IString::c2x ═══ Converts a normal string of characters to a string of hexadecimal digits. For example, this function changes 'a' to 61 and 'ab' to 6162. Note: This function is not locale sensitive. Overload 1 public: static IString c2x(const IString& aString); Overload 2 public: IString& c2x(); ═══ 1.39.14. IString::center ═══ Centers the receiver within a string of the specified length. Overload 1 public: static IString center( const IString& aString, unsigned length, char padCharacter = ' '); Overload 2 public: IString& center(unsigned length, char padCharacter = ' '); ═══ 1.39.15. IString::change ═══ Changes occurrences of a specified pattern to a specified replacement string. You can specify the number of changes to perform. The default is to change all occurrences of the pattern. You can also specify the position in the receiver at which to begin. The parameters are the following: inputString The pattern string as a reference to an object of type IString. The library searches for the pattern string within the receiver's data. pInputString The pattern string as NULL-terminated string. The library searches for the pattern string within the receiver's data. outputString The replacement string as a reference to an object of type IString. It replaces the occurrences of the pattern string in the receiver's data. pOutputString The replacement string as a NULL-terminated string. It replaces the occurrences of the pattern string in the receiver's data. startPos The position to start the search at within the receiver's data. The default is 1. numChanges The number of patterns to search for and change. The default is UINT_MAX, which causes changes to all occurrences of the pattern. Overload 1 public: static IString change( const IString& aString, const char* pInputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 2 public: IString& change( const IString& inputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 3 public: IString& change( const IString& inputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 4 public: IString& change( const char* pInputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 5 public: IString& change( const char* pInputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 6 public: static IString change( const IString& aString, const IString& inputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 7 public: static IString change( const IString& aString, const IString& inputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 8 public: static IString change( const IString& aString, const char* pInputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX); Overload 9 protected: IString& change( const char* pPattern, unsigned patternLen, const char* pReplacement, unsigned replacementLen, unsigned startPos, unsigned numChanges); ═══ 1.39.16. IString::charType ═══ Returns the type of the character at the specified index. public: IStringEnum::CharType charType(unsigned index) const; ═══ 1.39.17. IString::copy ═══ Replaces the receiver's contents with a specified number of replications of itself. Overload 1 public: static IString copy( const IString& aString, unsigned numCopies); Overload 2 public: IString& copy(unsigned numCopies); ═══ 1.39.18. IString::d2b ═══ Converts a string of decimal digits to a string of binary digits. This function builds the string eight bits at a time. For example, '12' gets converted to '00001100' '17' gets converted to '00010001' '123' gets converted to '01111011' Use stripLeading('0') to strip the leading zeros. Overload 1 public: IString& d2b(); Overload 2 public: static IString d2b(const IString& aString); ═══ 1.39.19. IString::d2c ═══ Converts a string of decimal digits to a normal string of characters. For example, this function changes 12 to \x0c and 56 to 8. Note: This function is not locale sensitive. Overload 1 public: static IString d2c(const IString& aString); Overload 2 public: IString& d2c(); ═══ 1.39.20. IString::d2x ═══ Converts a string of decimal digits to a string of hexadecimal digits. For example, this function changes 12 to c and 123 to 7b. Overload 1 public: static IString d2x(const IString& aString); Overload 2 public: IString& d2x(); ═══ 1.39.21. IString::data ═══ Returns the address of the contents of the IString. protected: char* data() const; ═══ 1.39.22. IString::defaultBuffer ═══ Returns a pointer to the contents of the nullBuffer data member. protected: static char* defaultBuffer(); ═══ 1.39.23. IString::findPhrase ═══ Locates a specified string of words for indexOfWord functions. protected: unsigned findPhrase( const IString& aPhrase, unsigned startWord, IndexType charOrWord) const; ═══ 1.39.24. IString::includes ═══ If the receiver contains the specified search string, true is returned. Overload 1 public: Boolean includes(const IString& aString) const; Overload 2 public: Boolean includes(const char* pString) const; Used in samples: Direct Manipulation Sample 2: dmsamp2.cpp Direct Manipulation Sample 4: dmsamp4.cpp Overload 3 public: Boolean includes(char aChar) const; Overload 4 public: Boolean includes(const IStringTest& aTest) const; ═══ 1.39.25. IString::includesDBCS ═══ If any characters are DBCS (double-byte character set), true is returned. Note: This function is interchangeable with includesMBCS. public: Boolean includesDBCS() const; ═══ 1.39.26. IString::includesMBCS ═══ If any characters are MBCS (multiple-byte character set), true is returned. Note: This function is interchangeable with includesDBCS. public: Boolean includesMBCS() const; ═══ 1.39.27. IString::includesSBCS ═══ If any characters are SBCS (single-byte character set), true is returned. public: Boolean includesSBCS() const; ═══ 1.39.28. IString::indexOf ═══ Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, 0 is returned. In addition to IStrings, you can also specify a single character or an IStringTest. Overload 1 public: unsigned indexOf( const char* pString, unsigned startPos = 1) const; Overload 2 public: unsigned indexOf( const IString& aString, unsigned startPos = 1) const; Overload 3 public: unsigned indexOf( char aCharacter, unsigned startPos = 1) const; Overload 4 public: unsigned indexOf( const IStringTest& aTest, unsigned startPos = 1) const; ═══ 1.39.29. IString::indexOfAnyBut ═══ Returns the index of the first character of the receiver that is not in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that fails the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyBut( const char* pValidChars, unsigned startPos = 1) const; Overload 2 public: unsigned indexOfAnyBut( const IString& validChars, unsigned startPos = 1) const; Overload 3 public: unsigned indexOfAnyBut( char validChar, unsigned startPos = 1) const; Overload 4 public: unsigned indexOfAnyBut( const IStringTest& aTest, unsigned startPos = 1) const; ═══ 1.39.30. IString::indexOfAnyOf ═══ Returns the index of the first character of the receiver that is a character in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that passes the test prescribed by a specified IStringTestobject. Overload 1 public: unsigned indexOfAnyOf( char searchChar, unsigned startPos = 1) const; Overload 2 public: unsigned indexOfAnyOf( const IString& searchChars, unsigned startPos = 1) const; Overload 3 public: unsigned indexOfAnyOf( const char* pSearchChars, unsigned startPos = 1) const; Overload 4 public: unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 1) const; ═══ 1.39.31. IString::indexOfPhrase ═══ Returns the position of the first occurrence of the specified phrase in the receiver. If the phrase is not found, 0 is returned. public: unsigned indexOfPhrase( const IString& wordString, unsigned startWord = 1) const; ═══ 1.39.32. IString::indexOfWord ═══ Returns the index of the specified white-space-delimited word in the receiver. If the word is not found, 0 is returned. Overload 1 public: unsigned indexOfWord(unsigned wordNumber) const; Overload 2 protected: unsigned indexOfWord( unsigned wordNumber, unsigned startPos, unsigned numWords) const; ═══ 1.39.33. IString::initBuffer ═══ Resets the contents from a specified buffer or buffers. Overload 1 protected: IString& initBuffer(long n); Overload 2 protected: IString& initBuffer(unsigned long n); Overload 3 protected: IString& initBuffer(double d); Overload 4 protected: IString& initBuffer( const void* p1, unsigned len1, const void* p2 = 0, unsigned len2 = 0, const void* p3 = 0, unsigned len3 = 0, char padChar = 0); ═══ 1.39.34. IString::insert ═══ Inserts the specified string after the specified location. Overload 1 public: static IString insert( const IString& aString, const char* pInsert, unsigned index = 0, char padCharacter = ' '); Overload 2 public: IString& insert( const IString& aString, unsigned index = 0, char padCharacter = ' '); Overload 3 public: IString& insert( const char* pString, unsigned index = 0, char padCharacter = ' '); Overload 4 public: static IString insert( const IString& aString, const IString& anInsert, unsigned index = 0, char padCharacter = ' '); Overload 5 protected: IString& insert( const char* pInsert, unsigned insertLen, unsigned startPos, char padCharacter); ═══ 1.39.35. IString::isAbbrevFor ═══ If the receiver is a valid abbreviation of the specified string, true is returned. The parameters are the following: pFullString The full string for the abbreviation check. The string can be either a NULL-terminated character string or not. fullLen The full length of the specified pFullString minus the null terminator. minLen The minimum length to match for it to be a valid abbreviation. If you specify 0, the minimum length is the length of the receiver's string. protected: Boolean isAbbrevFor( const char* pFullString, unsigned fullLen, unsigned minLen) const; ═══ 1.39.36. IString::isAbbreviationFor ═══ If the receiver is a valid abbreviation of the specified string, true is returned. The parameters are the following: fullString The full string for the abbreviation check is contained in another IString. pFullString The full string for the abbreviation check is a NULL-terminated character string. minAbbrevLength The minimum length to match for it to be a valid abbreviation. The default minimum length is 0, which means the minimum length is the length of the receiver's string. Overload 1 public: Boolean isAbbreviationFor( const IString& fullString, unsigned minAbbrevLength = 0) const; Overload 2 public: Boolean isAbbreviationFor( const char* pFullString, unsigned minAbbrevLength = 0) const; ═══ 1.39.37. IString::isAlphabetic ═══ If all the characters are in {'A'-'Z','a'-'z'}, true is returned. public: Boolean isAlphabetic() const; Used in samples: Notify Sample: notify.cpp Lancelot - A Valiant Example: lproject.cpp ═══ 1.39.38. IString::isAlphanumeric ═══ If all the characters are in {'A'-'Z','a'-'z','0'-'9'}, true is returned. public: Boolean isAlphanumeric() const; Used in samples: Lancelot - A Valiant Example: lgenl.cpp Lancelot - A Valiant Example: lacct.cpp Lancelot - A Valiant Example: lbadge.cpp Lancelot - A Valiant Example: lskill.cpp Lancelot - A Valiant Example: lstatus.cpp ═══ 1.39.39. IString::isASCII ═══ If all the characters are in {0x00-0x7F}, true is returned. public: Boolean isASCII() const; ═══ 1.39.40. IString::isBinaryDigits ═══ If all the characters are either 0 or 1, true is returned. public: Boolean isBinaryDigits() const; ═══ 1.39.41. IString::isControl ═══ Returns true if all the characters are control characters. Control characters are determined using the iscntrl() C Library function defined in the cntrl locale source file and in the cntrl class of the LC_CTYPE category of the current locale. For example, on ASCII operating systems, control characters are those in the range {0x00-0x1F,0x7F}. public: Boolean isControl() const; ═══ 1.39.42. IString::isDBCS ═══ If all the characters are DBCS, true is returned. Note: This function is interchangeable with isMBCS. public: Boolean isDBCS() const; ═══ 1.39.43. IString::isDigits ═══ If all the characters are in {'0'-'9'}, true is returned. public: Boolean isDigits() const; ═══ 1.39.44. IString::isGraphics ═══ Returns true if all the characters are graphics characters. Graphics characters are printable characters excluding the space character, as defined by the isgraph() C Library function in the graph locale source file and in the graph class of the LC_CTYPE category of the current locale. On ASCII systems, for example, graphics characters are those in the range {0x21-0x7E}. public: Boolean isGraphics() const; ═══ 1.39.45. IString::isHexDigits ═══ If all the characters are in {'0'-'9','A'-'F','a'-'f'}, true is returned. public: Boolean isHexDigits() const; ═══ 1.39.46. IString::isLike ═══ If the receiver matches the specified pattern, which can contain wildcard characters, true is returned. You can use the first wildcard character to specify that 0 or more arbitrary characters are accepted. The default wildcard character that does this is *, but you can specify another character when calling IString::isLike. For example: IString( "Allison" ).isLike( "Al*ison" ) -> true You can use the second wildcard character to specify that a single arbitrary character is accepted. The default wildcard character that does this is ?, but you can specify another character when calling IString::isLike. For example: IString( "istring7.cpp" ).isLike( "i*.?pp" ) -> true IString( "Not a question!" ).isLike( "*?", '*', '-' ) -> false Overload 1 public: Boolean isLike( const IString& aPattern, char zeroOrMore = ' * ', char anyChar = '?') const; Overload 2 public: Boolean isLike( const char* pPattern, char zeroOrMore = ' * ', char anyChar = '?') const; Overload 3 protected: Boolean isLike( const char* pPattern, unsigned patternLen, char zeroOrMore, char anyChar) const; ═══ 1.39.47. IString::isLowerCase ═══ If all the characters are in {'a'-'z'}, true is returned. public: Boolean isLowerCase() const; ═══ 1.39.48. IString::isMBCS ═══ If all the characters are MBCS, true is returned. Note: This function is interchangeable with isDBCS. public: Boolean isMBCS() const; ═══ 1.39.49. IString::isPrintable ═══ Returns true if all the characters are printable characters. Printable characters are defined by the isprint() C Library function as defined in the print locale source file and in the print class of the LC_CTYPE category of the current locale. On ASCII systems, for example, printable characters are those in the range {0x20-0x7E}. public: Boolean isPrintable() const; ═══ 1.39.50. IString::isPunctuation ═══ If none of the characters is white space, a control character, or an alphanumeric character, true is returned. public: Boolean isPunctuation() const; ═══ 1.39.51. IString::isSBCS ═══ If all the characters are SBCS, true is returned. public: Boolean isSBCS() const; ═══ 1.39.52. IString::IString ═══ You can construct objects of this class in the following ways: Construct a NULL string. Construct a string with the ASCII representation of a given numeric value, supporting all flavors of integer and double. Construct a string with a copy of the specified character data, supporting ASCIIZ strings, characters, and IStrings. The character data passed is converted to its ASCII representation. Construct a string with contents that consist of copies of up to three buffers of arbitrary data (void*). Optionally, you only need to provide the length, in which case the IString contents are initialized to a specified pad character. The default character is a blank. These constructors can throw exceptions under the following conditions: Memory allocation errors Many factors dynamically allocate space and these allocation requests may fail. If so, the User Interface Class Library translates memory allocation errors into exceptions. Generally, such errors do not occur until you allocate an astronomical amount of storage. Out-of-range errors These occur if you attempt to construct an IString with a length greater than UINT_MAX. Overload 1 public: IString(short); Construct a string with the ASCII representation of a short numeric value. Overload 2 public: IString(); Construct a NULL string. Used in samples: Hello World Sample - Version 6: ahellow6.cpp Notify Sample: notify.cpp DDE Client Sample: aclient.cpp DDE Server Sample: aserver.cpp Direct Manipulation Sample 4: dmsamp4.cpp Overload 3 public: IString(const IString& aString); Construct a string with a copy of the specified IString. Used in samples: Hello World Sample - Version 4: ahellow4.cpp Hello World Sample - Version 6: ahellow6.cpp Multi-Line Entry Field Sample: amle.cpp Notify Sample: notify.cpp DDE Client Sample: aclient.cpp Overload 4 public: IString(int); Construct a string with the ASCII representation of an integer value. Used in samples: Hello World Sample - Version 6: ahellow6.cpp Version Sample: version.cpp Multimedia MMREMOTE Sample: mmremote.cpp Lancelot - A Valiant Example: ltimec.cpp Overload 5 public: IString(unsigned); Construct a string with the ASCII representation of an unsigned numeric value. Overload 6 public: IString(long); Construct a string with the ASCII representation of a long numeric value. Used in samples: DDE Client Sample: aclient.cpp Lancelot - A Valiant Example: ltimec.cpp Overload 7 public: IString(unsigned long); Construct a string with the ASCII representation of an unsigned long numeric value. Used in samples: List Box Sample: alistbox.cpp Set Canvas Sample: asetcv.cpp Container Clipboard Sample: clipbrd.cpp DDE Server Sample: aserver.cpp Multimedia MMREMOTE Sample: mmremote.cpp Overload 8 public: IString(unsigned short); Construct a string with the ASCII representation of an unsigned short numeric value. Overload 9 public: IString(double); Construct a string with the ASCII representation of a double numeric value. Overload 10 public: IString(char); Construct a string with a copy of the character. The string length is set to 1. Used in sample: Direct Manipulation Sample 4: dmsamp4.cpp Overload 11 public: IString(unsigned char); Construct a string with a copy of the unsigned character. The string length is set to 1. Overload 12 public: IString(signed char); Construct a string with a copy of the signed character. The string length is set to 1. Overload 13 public: IString(const char*); Construct a string with a copy of the specified ASCIIZ string. Used in samples: List Box Sample: alistbox.cpp Message Box Sample: msgbox.cpp Notify Sample: notify.cpp Tool Bar Sample 1: tbar1.cpp Tool Bar Sample 2: tbar2.cpp Overload 14 public: IString(const unsigned char*); Construct a string with a copy of the specified unsigned ASCIIZ string. Overload 15 public: IString(const signed char*); Construct a string with a copy of the specified signed ASCIIZ string. Overload 16 public: IString( const void* pBuffer1, unsigned lenBuffer1, char padCharacter = ' '); Construct a string with contents from one buffer of arbitrary data (void*). Overload 17 public: IString( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, char padCharacter = ' '); Construct a string with contents from two buffers of arbitrary data (void*). Overload 18 public: IString( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, const void* pBuffer3, unsigned lenBuffer3, char padCharacter = ' '); Construct a string with contents from three buffers of arbitrary data (void*). ═══ 1.39.53. IString::isUpperCase ═══ If all the characters are in {'A'-'Z'}, true is returned. public: Boolean isUpperCase() const; ═══ 1.39.54. IString::isValidDBCS ═══ If no DBCS characters have a 0 second byte, true is returned. Note: This function is interchangeable with isValidMBCS. public: Boolean isValidDBCS() const; ═══ 1.39.55. IString::isValidMBCS ═══ If no MBCS characters have a 0 second byte, true is returned. Note: This function is interchangeable with isValidDBCS. public: Boolean isValidMBCS() const; ═══ 1.39.56. IString::isWhiteSpace ═══ Returns true if all the characters are whitespace characters. Whitespace characters are defined by the isspace() C Library function as defined in the space locale source file and in the space class of the LC_CTYPE category of the current locale. For example, on ASCII systems, whitespace characters are those in the range {0x09-0x0D,0x20}. public: Boolean isWhiteSpace() const; ═══ 1.39.57. IString::lastIndexOf ═══ Returns the index of the last occurrence of the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The returned value is in the range 0 <= x <= startPos. The default of UINT_MAX starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 1 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOf( char aCharacter, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 2 public: unsigned lastIndexOf( const IString& aString, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 3 public: unsigned lastIndexOf( const char* pString, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 4 public: unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = ( unsigned ) UINT_MAX) const; ═══ 1.39.58. IString::lastIndexOfAnyBut ═══ Returns the index of the last character not in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of UINT_MAX starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 1 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 2 public: unsigned lastIndexOfAnyBut( const IString& validChars, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 3 public: unsigned lastIndexOfAnyBut( const char* pValidChars, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 4 public: unsigned lastIndexOfAnyBut( char validChar, unsigned startPos = ( unsigned ) UINT_MAX) const; ═══ 1.39.59. IString::lastIndexOfAnyOf ═══ Returns the index of the last character in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of UINT_MAX starts the search at the end of the receiver's string. If the search target is not found, 0 is returned. If you specify 1 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found. Overload 1 public: unsigned lastIndexOfAnyOf( char searchChar, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 2 public: unsigned lastIndexOfAnyOf( const IString& searchChars, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 3 public: unsigned lastIndexOfAnyOf( const char* pSearchChars, unsigned startPos = ( unsigned ) UINT_MAX) const; Overload 4 public: unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned startPos = ( unsigned ) UINT_MAX) const; ═══ 1.39.60. IString::leftJustify ═══ Left-justifies the receiver in a string of the specified length. If the new length (length) is larger than the current length, the string is extended by the pad character (padCharacter). The default pad character is a blank. Overload 1 public: IString& leftJustify( unsigned length, char padCharacter = ' '); Overload 2 public: static IString leftJustify( const IString& aString, unsigned length, char padCharacter = ' '); ═══ 1.39.61. IString::length ═══ Returns the length of the string, not counting the terminating NULL character. public: unsigned length() const; Used in samples: Tool Bar Sample 1: tbar1.cpp Tool Bar Sample 2: tbar2.cpp 2D Graphics Sample: 2d-draw.cpp Lancelot - A Valiant Example: linfowin.cpp ═══ 1.39.62. IString::lengthOf ═══ Returns the length of a C character array. protected: static unsigned lengthOf(const char* p); ═══ 1.39.63. IString::lengthOfWord ═══ Returns the length of the specified white-space-delimited word in the receiver. public: unsigned lengthOfWord(unsigned wordNumber) const; ═══ 1.39.64. IString::lineFrom ═══ Returns the next line from the specified input stream. This static function accepts an optional line delimiter, which defaults to \n. The resulting IString contains the characters up to the next occurrence of the delimiter. The delimiter character is skipped. If an EOF condition occurs, this function returns an IString whose contents are NULL. public: static IString lineFrom( istream& aStream, char delim = '\n'); ═══ 1.39.65. IString::lowerCase ═══ Translates all upper-case letters in the receiver to lower-case. Overload 1 public: IString& lowerCase(); Used in sample: Direct Manipulation Sample 2: dmsamp2.cpp Overload 2 public: static IString lowerCase(const IString& aString); ═══ 1.39.66. IString::maxLong ═══ The maximum value of a long, with 32-bit unsigned long integers. protected: static const char* maxLong; Presentation Manager: This value is "2147483647" on OS/2 with 32-bit unsigned long integers. ═══ 1.39.67. IString::null ═══ A string that contains no element. protected: static const char* null; ═══ 1.39.68. IString::nullBuffer ═══ A pointer to the null buffer's contents. protected: static char* nullBuffer; ═══ 1.39.69. IString::numWords ═══ Returns the number of words in the receiver. public: unsigned numWords() const; ═══ 1.39.70. IString::occurrencesOf ═══ Returns the number of occurrences of the specified IString, char*, char, or IStringTest. If you just want a Boolean test, this is slower than IString::indexOf. Overload 1 public: unsigned occurrencesOf( const IString& aString, unsigned startPos = 1) const; Overload 2 public: unsigned occurrencesOf( const char* pString, unsigned startPos = 1) const; Overload 3 public: unsigned occurrencesOf( char aCharacter, unsigned startPos = 1) const; Overload 4 public: unsigned occurrencesOf( const IStringTest& aTest, unsigned startPos = 1) const; Overload 5 protected: unsigned occurrencesOf( const char* pSearchString, unsigned searchLen, unsigned startPos) const; ═══ 1.39.71. IString::operator & ═══ Performs bitwise AND. This function can handle the following three forms: string1 & aString Both operands are of type IString. string1 & pString The first operand is an IString and the second is a NULL-terminated character string. pString & aString The first operand is a NULL-terminated character string and the second is an IString. Overload 1 public: IString operator &(const IString& aString) const; Overload 2 public: IString operator &(const char* pString) const; ═══ 1.39.72. IString::operator &= ═══ Performs bitwise AND and replaces the receiver. This function can handle the following two forms: string1 &= aString Both operands are of type IString. string1 &= pString The first operand is an IString and the second is a NULL-terminated character string. Overload 1 public: IString& operator &=(const IString& aString); Overload 2 public: IString& operator &=(const char* pString); ═══ 1.39.73. IString::operator + ═══ Concatenates two strings. This function can handle the following three forms: string1 + aString Both operands are of type IString. string1 + pString The first operand is an IString and the second is a NULL-terminated character string. pString + aString The first operand is a NULL-terminated character string and the second is an IString. Overload 1 public: IString operator +(const char* pString) const; Used in samples: Hello World Sample - Version 6: ahellow6.cpp Version Sample: version.cpp Container Clipboard Sample: clipbrd.cpp Multimedia MMSTEREO Sample: mltwave.cpp Lancelot - A Valiant Example: lmainwin.cpp Overload 2 public: IString operator +(const IString& aString) const; Used in samples: List Box Sample: alistbox.cpp Multi Cell Canvas Sample: amcelcv.cpp Container Clipboard Sample: clipbrd.cpp DDE Client Sample: aclient.cpp DDE Server Sample: aserver.cpp ═══ 1.39.74. IString::operator += ═══ Concatenates the specified string to the receiver and replaces the receiver. This function can handle the following two forms: string1 += aString Both operands are of type IString. string1 += pString The first operand is an IString and the second is a NULL-terminated character string. Overload 1 public: IString& operator +=(const char* pString); Used in samples: Multi-Line Entry Field Sample: amle.cpp Lancelot - A Valiant Example: lpagectl.cpp Overload 2 public: IString& operator +=(const IString& aString); Used in samples: Multi-Line Entry Field Sample: amle.cpp Message Box Sample: msgbox.cpp Multi Cell Canvas Sample: amcelcv.cpp Direct Manipulation Sample 4: dmsamp4.cpp Lancelot - A Valiant Example: lproject.cpp ═══ 1.39.75. IString::operator = ═══ Replaces the contents of the string. public: IString& operator =(const IString& aString); Used in samples: Hello World Sample - Version 4: adialog4.cpp Hello World Sample - Version 5: adialog5.cpp Hello World Sample - Version 6: ahellow6.cpp Multi-Line Entry Field Sample: amle.cpp Notify Sample: notify.cpp ═══ 1.39.76. IString::operator char * ═══ Returns a char* pointer to the string's contents. public: operator char *() const; ═══ 1.39.77. IString::operator signed char * ═══ Returns a signed char* pointer to the string's contents. public: operator signed char *() const; ═══ 1.39.78. IString::operator unsigned char * ═══ Returns an unsigned char* pointer to the string's contents. public: operator unsigned char *() const; ═══ 1.39.79. IString::operator [] ═══ Returns a reference to the specified character of the string. Note: If you call the non-const version of this function with an index beyond the end, the function extends the string. Overload 1 public: char& operator [](unsigned index); Overload 2 public: const char& operator [](unsigned index) const; Exceptions ┌────────────────────┬────────────────────────────────────────┐ │IInvalidRequest │Passed an index larger than the string │ │ │size. Possible causes include, boundary │ │ │errors and using this function instead │ │ │of the non-const version which grows the│ │ │underlying IString buffer to accommodate│ │ │the index value. │ └────────────────────┴────────────────────────────────────────┘ ═══ 1.39.80. IString::operator ^ ═══ Performs bitwise XOR. This function can handle the following three forms: string1 ^ aString Both operands are of type IString. string1 ^ pString The first operand is an IString and the second is a NULL-terminated character string. pString ^ aString The first operand is a NULL-terminated character string and the second is an IString. Overload 1 public: IString operator ^(const IString& aString) const; Overload 2 public: IString operator ^(const char* pString) const; ═══ 1.39.81. IString::operator ^= ═══ Performs bitwise XOR and replaces the receiver. This function can handle the following two forms: string1 ^= aString Both operands are of type IString. string1 ^= pString The first operand is an IString and the second is a NULL-terminated character string. Overload 1 public: IString& operator ^=(const char* pString); Overload 2 public: IString& operator ^=(const IString& aString); ═══ 1.39.82. IString::operator | ═══ Performs bitwise OR. This function can handle the following three forms: string1 | aString Both operands are of type IString. string1 | pString The first operand is an IString and the second is a NULL-terminated character string. pString | aString The first operand is a NULL-terminated character string and the second is an IString. Overload 1 public: IString operator |(const char* pString) const; Overload 2 public: IString operator |(const IString& aString) const; ═══ 1.39.83. IString::operator |= ═══ Performs bitwise OR and replaces the receiver with the resulting string. This function can handle the following two forms: string1 |= aString Both operands are of type IString. string1 |= pString The first operand is an IString and the second is a NULL-terminated character string. Overload 1 public: IString& operator |=(const IString& aString); Overload 2 public: IString& operator |=(const char* pString); ═══ 1.39.84. IString::operator ~ ═══ Returns the string's bitwise negation (the string's complement). public: IString operator ~() const; ═══ 1.39.85. IString::overlayWith ═══ Replaces a specified portion of the receiver's contents with the specified string. The overlay starts in the receiver's data at the index, which defaults to 1. If index is beyond the end of the receiver's data, it is padded with the pad character (padCharacter). Overload 1 public: IString& overlayWith( const char* pString, unsigned index = 1, char padCharacter = ' '); Overload 2 public: IString& overlayWith( const IString& aString, unsigned index = 1, char padCharacter = ' '); Overload 3 public: static IString overlayWith( const IString& aString, const IString& anOverlay, unsigned index = 1, char padCharacter = ' '); Overload 4 public: static IString overlayWith( const IString& aString, const char* pOverlay, unsigned index = 1, char padCharacter = ' '); Overload 5 protected: IString& overlayWith( const char* pOverlay, unsigned overlayLen, unsigned index, char padCharacter); ═══ 1.39.86. IString::remove ═══ Deletes the specified portion of the string (that is, the substring) from the receiver. You can use this function to truncate an IString object at a specific position. For example: aString.remove(8); removes the substring beginning at index 8 and takes the rest of the string as a default. Overload 1 public: IString& remove(unsigned startPos); Overload 2 public: IString& remove(unsigned startPos, unsigned numChars); Overload 3 public: static IString remove( const IString& aString, unsigned startPos); Overload 4 public: static IString remove( const IString& aString, unsigned startPos, unsigned numChars); ═══ 1.39.87. IString::removeWords ═══ Deletes the specified words from the receiver's contents. You can specify the words by using a starting word number and the number of words. The latter defaults to the rest of the string. Note: The static functions IString::spaceand IString::removeWords obtain the same result but do not affect the String to which they are applied. Overload 1 public: IString& removeWords(unsigned firstWord, unsigned numWords); Overload 2 public: IString& removeWords(unsigned firstWord); Overload 3 public: static IString removeWords( const IString& aString, unsigned startWord); Overload 4 public: static IString removeWords( const IString& aString, unsigned startWord, unsigned numWords); ═══ 1.39.88. IString::reverse ═══ Reverses the receiver's contents. Overload 1 public: IString& reverse(); Overload 2 public: static IString reverse(const IString& aString); ═══ 1.39.89. IString::rightJustify ═══ Right-justifies the receiver in a string of the specified length. If the receiver's data is shorter than the requested length (length), it is padded on the left with the pad character (padCharacter). The default pad character is a blank. Overload 1 public: IString& rightJustify( unsigned length, char padCharacter = ' '); Overload 2 public: static IString rightJustify( const IString& aString, unsigned length, char padCharacter = ' '); ═══ 1.39.90. IString::setBuffer ═══ Sets the private data member to point to a new IBufferobject. protected: IString& setBuffer(IBuffer* ibuff); ═══ 1.39.91. IString::size ═══ Returns the length of the string, not counting the terminating NULL character. public: unsigned size() const; Used in samples: Multi-Line Entry Field Sample: amle.cpp Container Clipboard Sample: clipbrd.cpp DDE Client Sample: aclient.cpp ═══ 1.39.92. IString::space ═══ Modifies the receiver so that all words are separated by the specified number of blanks. The default is one blank. All white space is converted to simple blanks. Note: The static functions IString::space and IString::removeWords obtain the same result but do not affect the String to which they are applied. Overload 1 public: static IString space( const IString& aString, unsigned numSpaces = 1, char spaceChar = ' '); Overload 2 public: IString& space( unsigned numSpaces = 1, char spaceChar = ' '); ═══ 1.39.93. IString::strip ═══ Strips both leading and trailing character or characters. You can specify the character or characters as the following: A single char A char* array An IStringobject An IStringTestobject The default is white space. Overload 1 public: IString& strip(); Overload 2 public: IString& strip(char aCharacter); Overload 3 public: IString& strip(const IString& aString); Overload 4 public: IString& strip(const char* pString); Overload 5 public: IString& strip(const IStringTest& aTest); Overload 6 public: static IString strip(const IString& aString, char aChar); Overload 7 public: static IString strip( const IString& aString, const IString& aStringOfChars); Overload 8 public: static IString strip( const IString& aString, const char* pStringOfChars); Overload 9 public: static IString strip( const IString& aString, const IStringTest& aTest); Overload 10 protected: IString& strip( const char* p, unsigned len, IStringEnum::StripMode mode); Overload 11 protected: IString& strip( const IStringTest& aTest, IStringEnum::StripMode mode); ═══ 1.39.94. IString::stripBlanks ═══ Strips both leading and trailing white space. Note: This function is the static version of IString::strip, which has been renamed to avoid a duplicate definition. public: static IString stripBlanks(const IString& aString); ═══ 1.39.95. IString::stripLeading ═══ Strips the leading character or characters. Overload 1 public: static IString stripLeading( const IString& aString, const IString& aStringOfChars); Overload 2 public: IString& stripLeading(); Overload 3 public: IString& stripLeading(char aCharacter); Overload 4 public: IString& stripLeading(const IString& aString); Overload 5 public: IString& stripLeading(const char* pString); Overload 6 public: IString& stripLeading(const IStringTest& aTest); Overload 7 public: static IString stripLeading( const IString& aString, char aChar); Overload 8 public: static IString stripLeading( const IString& aString, const char* pStringOfChars); Overload 9 public: static IString stripLeading( const IString& aString, const IStringTest& aTest); ═══ 1.39.96. IString::stripLeadingBlanks ═══ Strips the leading character or characters. Note: This function is the static version of IString::stripLeading, which has been renamed to avoid a duplicate definition. public: static IString stripLeadingBlanks(const IString& aString); ═══ 1.39.97. IString::stripTrailing ═══ Strips the trailing character or characters. Overload 1 public: static IString stripTrailing( const IString& aString, char aChar); Overload 2 public: IString& stripTrailing(); Overload 3 public: IString& stripTrailing(char aCharacter); Overload 4 public: IString& stripTrailing(const IString& aString); Overload 5 public: IString& stripTrailing(const char* pString); Overload 6 public: IString& stripTrailing(const IStringTest& aTest); Overload 7 public: static IString stripTrailing( const IString& aString, const IString& aStringOfChars); Overload 8 public: static IString stripTrailing( const IString& aString, const char* pStringOfChars); Overload 9 public: static IString stripTrailing( const IString& aString, const IStringTest& aTest); ═══ 1.39.98. IString::stripTrailingBlanks ═══ Strips the trailing character or characters. Note: This function is the static version of IString::stripTrailing, which has been renamed to avoid a duplicate definition. public: static IString stripTrailingBlanks(const IString& aString); ═══ 1.39.99. IString::subString ═══ Returns a specified portion of the string (that is, the substring) of the receiver. The parameters are the following: startPos The starting position of the substring being extracted. If this position is beyond the end of the data in the receiver, this function returns a NULL IString. length The length of the substring to be extracted. If the length extends beyond the end of the receiver's data, the returned IString is padded to the specified length with padCharacter. If you do not specify length and it defaults, this function uses the rest of the receiver's data starting from startPos for padding. padCharacter The character the function uses as padding if the requested length extends beyond the end of the receiver's data. The default padCharacter is a blank. You can use this function to truncate an IString object at a specific position. For example: aString = aString.subString(1, 7); returns the substring concluding with index 7 and discards the rest of the string. Overload 1 public: IString subString( unsigned startPos, unsigned length, char padCharacter = ' ') const; Overload 2 public: IString subString(unsigned startPos) const; ═══ 1.39.100. IString::translate ═══ Converts all of the receiver's characters that are in the first specified string to the corresponding character in the second specified string. Overload 1 public: static IString translate( const IString& aString, const char* pInputChars, const IString& outputChars, char padCharacter = ' '); Overload 2 public: IString& translate( const IString& inputChars, const IString& outputChars, char padCharacter = ' '); Overload 3 public: IString& translate( const IString& inputChars, const char* pOutputChars, char padCharacter = ' '); Overload 4 public: IString& translate( const char* pInputChars, const IString& outputChars, char padCharacter = ' '); Overload 5 public: IString& translate( const char* pInputChars, const char* pOutputChars, char padCharacter = ' '); Overload 6 public: static IString translate( const IString& aString, const IString& inputChars, const IString& outputChars, char padCharacter = ' '); Overload 7 public: static IString translate( const IString& aString, const IString& inputChars, const char* pOutputChars, char padCharacter = ' '); Overload 8 public: static IString translate( const IString& aString, const char* pInputChars, const char* pOutputChars, char padCharacter = ' '); Overload 9 protected: IString& translate( const char* pInputChars, unsigned inputLen, const char* pOutputChars, unsigned outputLen, char padCharacter); ═══ 1.39.101. IString::upperCase ═══ Translates all lower-case letters in the receiver to upper-case. Overload 1 public: static IString upperCase(const IString& aString); Overload 2 public: IString& upperCase(); ═══ 1.39.102. IString::word ═══ Returns a copy of the specified white-space-delimited word in the receiver. public: IString word(unsigned wordNumber) const; ═══ 1.39.103. IString::wordIndexOfPhrase ═══ Returns the word number of the first word in the receiver that matches the specified phrase. The function starts its search with the word number you specify in startWord, which defaults to 1. If the phrase is not found, 0 is returned. public: unsigned wordIndexOfPhrase( const IString& aPhrase, unsigned startWord = 1) const; ═══ 1.39.104. IString::words ═══ Returns a substring of the receiver that starts at a specified word and is comprised of a specified number of words. The word separators are copied to the result intact. Overload 1 public: IString words(unsigned firstWord, unsigned numWords) const; Overload 2 public: IString words(unsigned firstWord) const; ═══ 1.39.105. IString::x2b ═══ Converts a string of hexadecimal digits to a string of binary digits. For example, this function changes a1c to 101000011100 and f3 to 11110011. Overload 1 public: static IString x2b(const IString& aString); Overload 2 public: IString& x2b(); ═══ 1.39.106. IString::x2c ═══ Converts a string of hexadecimal digits to a normal string of characters. For example, this function changes 8 to \x08 and 31393935 to 1995. Note: This function is not locale sensitive. Overload 1 public: IString& x2c(); Overload 2 public: static IString x2c(const IString& aString); ═══ 1.39.107. IString::x2d ═══ Converts a string of hexadecimal digits to a string of decimal digits. For example, this function changes a1c to 2588 and 10000 to 65536. Overload 1 public: IString& x2d(); Overload 2 public: static IString x2d(const IString& aString); ═══ 1.39.108. IString::zero ═══ The number 0. protected: static const char* zero; ═══ 1.39.109. IString::~IString ═══ public: ~IString(); ═══ Nested Types - IString ═══ Type Definitions BitOperator IndexType ═══ Type Definition - IString::BitOperator ═══ typedef enum { and , or , exclusiveOr } BitOperator; Use these enumerators to specify the bit operator to apply to the applyBitOp function. Valid bit operators are as follows: and or exclusiveOr ═══ Type Definition - IString::IndexType ═══ typedef enum { charIndex , wordIndex } IndexType; These enumerators specify whether the result from the findPhrase function is a word index or a character index: charIndex Returns the result as the byte index within the string wordIndex Returns the result as the index of the matching word. For example, the first word is 1, the second word is 2, and so forth. Related Enumeration BitOperator ═══ 1.40. IStringEnum ═══ Description Derivation Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IStringEnum ═══ Inherits from none. Inherited by none. ═══ Class Description - IStringEnum ═══ istrenum.hpp The IStringEnum class serves as a repository for enumeration types related to the IString class. The User Interface Class Library places these enumeration types here so they can easily be shared between code that implements the classes IString, IBuffer, and IDBCSBuffer. ═══ IStringEnum - Character Type ═══ This enum describes character set specifications, IBuffer and IDBCSBuffer use these. Note the code for mbcs must be the same as the length of the corresponding characters. ═══ IStringEnum - StripMode ═══ This enum supports stripping of characters from strings. ═══ Nested Types - IStringEnum ═══ Type Definitions CharType StripMode ═══ Type Definition - IStringEnum::CharType ═══ typedef enum { sbcs , dbcs1 = 1 , mbcs1 = 1 , dbcs2 = 2 , mbcs2 = 2 , mbcs3 = 3 , mbcs4 = 4 } CharType; These enumerators specify the various types of characters that comprise an IString: sbcs The IString contains single-byte character set (SBCS) characters. dbcs1 The IString contains the first byte of a double-byte character support (DBCS) character. dbcs2 The IString contains the second byte of a double-byte character support (DBCS) character. ═══ Type Definition - IStringEnum::StripMode ═══ typedef enum { leading , trailing , both } StripMode; Enumeration that defines the mode of various functions that strip leading characters, trailing characters, or both from IStrings. Related Enumeration CharType ═══ 1.41. IStringParser ═══ Description Derivation Public Functions Protected Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IStringParser ═══ IBase │ IStringParser Inherited by none. ═══ Class Description - IStringParser ═══ istparse.hpp Objects of this class enable you to parse the content of an IString and place portions of the string into other strings. You can limit the parsing of a string by specifying the following: Patterns that must be matched Relative or absolute column numbers This class's functions work much like the REXX parse statement. Typically, you create IStringParser objects implicitly by applying the right-shift operator to an IString. IStringParser also provides the right-shift operator as a member function so you can chain together invocations of the operator. For example, a typical expression using IStringParser objects might look like the following: aFileName >> drive >> ':' >> path; The right-shift operator does one of four things, depending on the type of the right-hand operand: IString The string parser object sets this string to the next token from the text being parsed. pattern The parser advances to the next character beyond the occurrence of that pattern in its text. The pattern can be any of the following: const char* Searches for the sequence of characters described by the character array. const IString Searches for the sequence of characters described by the string. Note that the treatment of a const IString is fundamentally different from the treatment of a non-const IString. char Searches for the next occurrence of the specified character. IStringTest Searches for the next character in the text for which the string test object returns true. . number The current parser text position is adjusted by the specified amount. The value can be positive or negative. special IStringParser defines special right-shift operands that perform the following special-purpose parser operations: IStringParser::reset This enumerator resets the parser text position to 1. IStringParser::skip This enumerator skips one token in the text. It is equivalent to >> temp, where temp is a temporary IString that is discarded. This is equivalent to using '.' in REXX. IStringParser::Skip An object of this class skips a given number of tokens. You can also use the left-shift operator with an unsigned numeric parameter. This repositions the parser object to the specified column. Note that the parameter is not relative as it is in the case of the right-shift operator. Instead, it is an absolute column position. ═══ Public Functions - IStringParser ═══ Absolute Column Positioning operator << Commands operator >> Constructors ~IStringParser Pattern Matching operator >> Relative Column Positioning operator >> Tokens operator >> Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IStringParser - Absolute Column Positioning ═══ Use these members to reset the parser text position to an absolute column number. ═══ IStringParser - Commands ═══ Use these members to permit special-purpose parsing techniques. They allow you to handle special commands and to skip objects. ═══ IStringParser - Constructors ═══ The destructor member is the default. The constructor members are protected to prevent you from creating objects except via use of the shift operators. You can construct a string parser object by providing: a string that defines the text to be parsed an existing parser object (copy constructor) Note that usually you will construct parser objects by applying the right-shift operator to a string. The constructor is protected to prevent you from creating objects except via use of those operators. Creation is prevented because of the nature of string parser objects. Since they hold references to operands, it is unwise to permit the objects to persist beyond the scope of those operands. ═══ IStringParser - Initialization ═══ Use these members to construct parser objects from strings. In effect, they implicitly construct an IStringParser object for you when you apply the ">>" or "<<" operators to a string. An expression of the form: aString >> x -or- aString << n is equivalent to IStringParser( aString ) >> x -or- IStringParser( aString ) << n These members are declared as friends simply so that their declaration appears within this class declaration. ═══ IStringParser - Pattern Matching ═══ Use these members to advance to the next occurrence of the argument pattern in the parser text. Upon return, the parser is positioned at the next character beyond the text that matched the pattern. If the pattern is not found, the parser is positioned off the end of the text. Note, that when using an IString as a pattern, you should cast it to a const IString reference. ═══ IStringParser - Relative Column Positioning ═══ Use these members to move the parser text position relative to its current position. A negative argument moves backward; a positive argument moves forward. The adjustment is made starting at the point at which the prior parsing instruction started. For example: "1234" >> token1 >> 1 >> token2 >> 2 >> token3; will result in: token1 == "1" token2 == "23" token3 == "4". ═══ IStringParser - Tokens ═══ Use these members to parse the next token from the parser object and place it into the IString operand. By necessity, these members place the rest of the parser text into the string. When the parser encounters a subsequent parsing instruction, it goes back and adjusts the token placed into the string. For example: "token1 token2" >> token1 // token1 == token1 token2 at this point >> token2; // token2 == "token2" and // token1 == "token1". ═══ Protected Functions - IStringParser ═══ Constructors IStringParser ═══ Protected Data - IStringParser ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.41.1. IStringParser::IStringParser ═══ The destructor member is the default. The constructor members are protected to prevent you from creating objects except via use of the shift operators. You can construct a string parser object by providing: a string that defines the text to be parsed an existing parser object (copy constructor) Note that usually you will construct parser objects by applying the right-shift operator to a string. The constructor is protected to prevent you from creating objects except via use of those operators. Creation is prevented because of the nature of string parser objects. Since they hold references to operands, it is unwise to permit the objects to persist beyond the scope of those operands. Overload 1 protected: IStringParser(const IString& text); Construct an object from an IString object. The IString object specifies the text string to parse. Overload 2 protected: IStringParser(const IStringParser& parser); Construct an object from an existing IStringParser object. The IStringParser object specifies the text string to parse. This constructor increments the usage count of the IStringParser object. ═══ 1.41.2. IStringParser::operator << ═══ Changes the parser text position to an absolute column number. This is a left-shift operator. public: IStringParser& operator <<(unsigned long position); ═══ 1.41.3. IStringParser::operator >> ═══ Parses the text string. The right-shift operator is the primary function for parsing the text string. The User Interface Class Library overloads this function so you can specify how you want the text string parsed via the type of parameter accepted by a particular overload. Overload 1 public: IStringParser& operator >>(const IStringTest& test); Applies the IStringTest object to the parser text and moves the parser text position to the next character that satisfies the string test. If the string test is not satisfied, the parser moves the position off the end of the parser text. Overload 2 public: IStringParser& operator >>(Command command); Resets the parser text position as follows: To the beginning of the text To skip the next token in the parser text Use the enumeration IStringParser::Command to specify the parsing token. Overload 3 public: IStringParser& operator >>(const SkipWords& skipObject); Skips the next n words in the parser text, where n is the number of words specified when constructing the IStringParser::SkipWords object. Overload 4 public: IStringParser& operator >>(IString& token); Parses the next token from the object into the IString object. This parameter places the rest of the parser text into the IString object. When the parser encounters a subsequent parsing instruction, it adjusts the token placed into the string. For example: token1 token2 >> token1 // token1 == "token1 token2" at this point >> token2; // token2 == token2 and // token1 == token1. Used in sample: Container Clipboard Sample: clipbrd.cpp Overload 5 public: IStringParser& operator >>(const IString& pattern); Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text. Overload 6 public: IStringParser& operator >>(const char* pattern); Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text. Overload 7 public: IStringParser& operator >>(char pattern); Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text. Overload 8 public: IStringParser& operator >>(int delta); Moves the parser text position relative to the current parser text position. For example: "1234" >> token1 >> 1 >> token2 >> 2 >> token3; results in: token1 == "1" token2 == "23" token3 == "4" Overload 9 public: IStringParser& operator >>(unsigned long delta); Moves the parser text position relative to the current parser text position. For example: "1234" >> token1 >> 1 >> token2 >> 2 >> token3; results in: token1 == "1" token2 == "23" token3 == "4" ═══ 1.41.4. IStringParser::~IStringParser ═══ public: ~IStringParser(); Destructor, decrements reference count. ═══ Nested Types - IStringParser ═══ Classes IStringParser::SkipWords Enumerations Command ═══ Enums - Command ═══ enum Command { reset, skipWord, skip=skipWord }; These enumerators specify special purpose parsing tokens: reset Resets the parser position to 1. skip Causes the parser to skip one token (that is, a word) in the input text. ═══ 1.42. IStringParser::SkipWords ═══ Description Derivation Constructors Public Functions Protected Data To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IStringParser::SkipWords ═══ IBase │ IStringParser::SkipWords Inherited by none. ═══ Class Description - IStringParser::SkipWords ═══ istparse.hpp Objects of the nested class IStringParser::SkipWords skip a specified number of words in the input text without assigning those words to output strings. Use these objects when parsing text with the class IStringParser. ═══ Public Functions - IStringParser::SkipWords ═══ Constructors SkipWords Word Functions numberOfWords Inherited Members IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IStringParser::SkipWords - Constructors ═══ You can construct objects of this class by specifying the number of words to skip. Use in conjunction with IStringParser objects to parse the content of an IString and place portions of the string into other strings. ═══ IStringParser::SkipWords - Obsolete Data and Functions ═══ ═══ IStringParser::SkipWords - Word Functions ═══ Use these members to retrieve the number of words to skip. You set the number of words to skip in the constructor. ═══ Protected Data - IStringParser::SkipWords ═══ Inherited Members IBase recoverable unrecoverable ═══ 1.42.1. IStringParser::SkipWords::numberOfWords ═══ Returns the number of words to skip. public: unsigned long numberOfWords() const; ═══ 1.42.2. IStringParser::SkipWords::SkipWords ═══ You can construct objects of this class by specifying the number of words to skip. The default is one word. public: SkipWords(unsigned long numberOfWords = 1); ═══ 1.43. IStringTest ═══ Description Derivation Constructors Public Functions Protected Functions Protected Data Nested Types To close all the panels in a chapter, double click on this panel's system menu. ═══ Derivation - IStringTest ═══ IBase │ IVBase │ IStringTest Inherited by: IStringTestMemberFn ═══ Class Description - IStringTest ═══ istrtest.hpp The IStringTest class defines the basic protocol for test objects that you can pass to IStringsor I0Strings to assist in performing various test and search functions. This class also provides concrete implementation for the common case of using a C function for such testing. The User Interface Class Library provides a derived template class, IStringTestMemberFn, to facilitate using member functions of any class on the IString functions that support IStringTest. Derived classes should re-implement the virtual function IStringTest::test to test characters passed by the IString and return the appropriate result. A constructor for this class accepts a pointer to a C function that in turn accepts an integer as a parameter and returns a Boolean. You can use such functions anywhere an IStringTest can be used. Note that this is the type of the standard C library "is" functions that check the type of C characters. ═══ Public Functions - IStringTest ═══ Constructors IStringTest ~IStringTest Testing test Inherited Members IVBase asDebugInfo asString IBase asDebugInfo asString messageFile messageText setMessageFile version ═══ IStringTest - Constructors ═══ You can construct and destruct objects of this class with a pointer to the C function to be used to implement the member IStringTest::test. Such members can be used anywhere an IStringTest can be used. Note that these members are the same as the standard C library is.... functions that check the type of C characters. This class also provides a protected constructor, which derived classes can use to reuse the space for the C/C++ function pointer. ═══ IStringTest - Function Types ═══ Use these typedefs to identify the test function. ═══