occt/src/Message/Message_Msg.cdl

-- Created on: 2001-01-18
-- Created by: OCC Team
-- Copyright (c) 2001-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.



class Msg  from Message

    ---Purpose: This class provides a tool for constructing the parametrized message
    --          basing on resources loaded by Message_MsgFile tool.
    --           
    --          A Message is created from a keyword: this keyword identifies the 
    --          message in a message file that should be previously loaded by call
    --          to Message_MsgFile::LoadFile(). 
    --          
    --          The text of the message can contain placeholders for the parameters
    --          which are to be filled by the proper values when the message 
    --          is prepared. Most of the format specifiers used in C can be used,
    --          for instance, %s for string, %d for integer etc. In addition,
    --          specifier %f is supported for double numbers (for compatibility
    --          with previous versions).
    --          
    --          User fills the parameter fields in the text of the message by 
    --          calling corresponding methods Arg() or operators "<<".
    --          
    --          The resulting message, filled with all parameters, can be obtained
    --          by method Get(). If some parameters were not filled, the text
    --          UNKNOWN is placed instead.

uses

    AsciiString  from TCollection,
    HAsciiString  from TCollection,
    ExtendedString from TCollection,
    HExtendedString from TCollection,
    SequenceOfInteger from TColStd

is

    Create returns Msg from Message;
    	---Purpose : Empty constructor

    Create (theMsg: Msg from Message) returns Msg from Message;
    	---Purpose : Copy constructor

    Create (theKey: CString) returns Msg from Message;
    	---Purpose : Create a message using a corresponding entry in Message_MsgFile

    Create (theKey: ExtendedString from TCollection) returns Msg from Message;
    	---Purpose : Create a message using a corresponding entry in Message_MsgFile

    Set (me: in out; theMsg: CString);
    	---Purpose : Set a message body text -- can be used as alternative to 
	--           using messages from resource file

    Set (me: in out; theMsg: ExtendedString from TCollection);
    	---Purpose : Set a message body text -- can be used as alternative to 
	--           using messages from resource file

    -- Adding arguments

    Arg (me: in out; theString : CString)
    returns Msg from Message;
    	---C++: return &
    	---C++: alias operator <<
    	---Purpose : Set a value for %..s conversion
    
    Arg (me: in out; theString : AsciiString from TCollection)
    returns Msg from Message;
    	---C++: return &
    	---C++: inline
    	---C++: alias operator <<
    	---Purpose : Set a value for %..s conversion

    Arg (me: in out; theString : HAsciiString from TCollection)
    returns Msg from Message;
    	---C++: return &
    	---C++: inline
    	---C++: alias operator <<
    	---Purpose : Set a value for %..s conversion

    Arg (me: in out; theString : ExtendedString from TCollection)
    returns Msg from Message;
    	---C++: return &
    	---C++: alias operator <<
    	---Purpose : Set a value for %..s conversion

    Arg (me: in out; theString : HExtendedString from TCollection)
    returns Msg from Message;
    	---C++: return &
    	---C++: inline
    	---C++: alias operator <<
    	---Purpose : Set a value for %..s conversion

    Arg (me: in out; theInt : Integer)
    returns Msg from Message;
    	---C++: return &
    	---C++: alias operator <<
    	---Purpose : Set a value for %..d, %..i, %..o, %..u, %..x or %..X conversion

    Arg (me: in out; theReal : Real)
    returns Msg from Message;
    	---C++: return &
    	---C++: alias operator <<
    	---Purpose : Set a value for %..f, %..e, %..E, %..g or %..G conversion

    Original (me) returns ExtendedString from TCollection;
    	---C++: inline
    	---C++: return const &
    	---Purpose : Returns the original message text
    
    Value (me) returns ExtendedString from TCollection;
    	---C++: inline
    	---C++: return const &
    	---Purpose : Returns current state of the message text with 
        --           parameters to the moment
    
    IsEdited (me) returns Boolean;
    	---C++: inline
    	---Purpose : Tells if Value differs from Original
    
    Get (me: in out)
    returns ExtendedString from TCollection;
    	---C++: return const &
    	---C++: alias "operator const TCollection_ExtendedString& () { return Get(); }"
    	---Purpose : Return the resulting message string with all parameters
	--           filled. If some parameters were not yet filled by calls
	--           to methods Arg (or <<), these parameters are filled by
	--           the word UNKNOWN

    -- Private methods
	
    getFormat (me: in out; theType : Integer;
                   theFormat : in out AsciiString from TCollection)
    returns Integer is private;

    replaceText (me: in out; theFirst : Integer;
                             theNb    : Integer;
                             theStr   : ExtendedString from TCollection) is private;

fields

    myOriginal     : ExtendedString    from TCollection;
    myMessageBody  : ExtendedString    from TCollection;
    mySeqOfFormats : SequenceOfInteger from TColStd;

end Msg;