-- Created on: 2007-06-28
-- Created by: OCC Team
-- Copyright (c) 2007-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and / or modify it
-- under the terms of the GNU Lesser General Public version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class Messenger from Message inherits TShared from MMgt

    ---Purpose: Messenger is API class providing general-purpose interface for 
    --          libraries that may issue text messages without knowledge
    --          of how these messages will be further processed.
    --          
    --          The messenger contains a sequence of "printers" which can be 
    --          customized by the application, and dispatches every received 
    --          message to all the printers.
    --  
    --          For convenience, a number of operators << are defined with left
    --          argument being Handle(Message_Messenger); thus it can be used
    --          with syntax similar to C++ streams.
    --          Note that all these operators use trace level Warning.

uses

    Printer            from Message,
    PrinterOStream     from Message,
    SequenceOfPrinters from Message,
    Gravity            from Message,
    AsciiString        from TCollection,
    ExtendedString     from TCollection    

is

    Create returns Messenger from Message;
    	---Purpose: Empty constructor; initializes by single printer directed to cout.
	--          Note: the default messenger is not empty but directed to cout
	--          in order to protect against possibility to forget defining printers.
	--          If printing to cout is not needed, clear messenger by GetPrinters().Clear()

    Create (thePrinter: Printer from Message)
    returns Messenger from Message;
    	---Purpose: Create messenger with single printer

    AddPrinter (me: mutable; thePrinter: Printer from Message)
    returns Boolean from Standard;
    	---Purpose: Add a printer to the messenger.
	--          The printer will be added only if it is not yet in the list.
	--          Returns True if printer has been added.

    RemovePrinter (me: mutable; thePrinter: Printer from Message)
    returns Boolean from Standard;
    	---Purpose: Removes specified printer from the messenger.
	--          Returns True if this printer has been found in the list 
        --          and removed.

    RemovePrinters (me: mutable; theType: Type from Standard)
    returns Integer from Standard;
    	---Purpose: Removes printers of specified type (including derived classes)
        --          from the messenger.
	--          Returns number of removed printers.

    Printers(me)
    returns SequenceOfPrinters from Message;
	---C++: inline
        ---C++: return const &
	---Purpose: Returns current sequence of printers
	
    ChangePrinters(me: mutable)
    returns SequenceOfPrinters from Message;
	---C++: inline
        ---C++: return &
	---Purpose: Returns sequence of printers
	--          The sequence can be modified.
	
    Send (me; theString : CString from Standard;
              theGravity: Gravity from Message = Message_Warning;
	      putEndl: Boolean from Standard = Standard_True);
    	---Purpose: Dispatch a message to all the printers in the list.
	--          Three versions of string representations are accepted for 
	--          convenience, by default all are converted to ExtendedString.
	--          The parameter putEndl specifies whether the new line should 
	--          be started after this message (default) or not (may have 
	--          sense in some conditions).

    Send (me; theString : AsciiString from TCollection;
              theGravity: Gravity from Message =  Message_Warning;
	      putEndl: Boolean from Standard = Standard_True);
    	---Purpose: See above

    Send (me; theString : ExtendedString from TCollection;
              theGravity: Gravity from Message = Message_Warning;
	      putEndl: Boolean from Standard = Standard_True);
    	---Purpose: See above

fields

    myPrinters: SequenceOfPrinters from Message;

end Messenger;