OCCT/src/IFSelect/IFSelect_SignatureList.cdl

-- Created on: 1994-10-27
-- Created by: Christian CAILLET
-- Copyright (c) 1994-1999 Matra Datavision
-- Copyright (c) 1999-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 SignatureList  from IFSelect  inherits TShared

    ---Purpose : A SignatureList is given as result from a Counter (any kind)
    --           It gives access to a list of signatures, with counts, and
    --           optionally with list of corresponding entities
    --           
    --           It can also be used only to give a signature, through SignOnly
    --           Mode. This can be useful for a specific counter (used in a
    --           Selection), while it remains better to use a Signature
    --           whenever possible

uses CString, HSequenceOfTransient,
     DictionaryOfInteger, DictionaryOfTransient, 
     AsciiString from TCollection,
     HAsciiString from TCollection, 
     HSequenceOfHAsciiString from TColStd,
     Messenger from Message,
     InterfaceModel, PrintCount

is

    Create (withlist : Boolean = Standard_False) returns mutable SignatureList;
    ---Purpose : Creates a SignatureList. If <withlist> is True, entities will
    --           be not only counted per signature, but also listed.

    SetList (me : mutable; withlist : Boolean);
    ---Purpose : Changes the record-list status. The list is not cleared but
    --           its use changes

    ModeSignOnly (me : mutable) returns Boolean;
    ---Purpose : Returns modifiable the SignOnly Mode
    --           If False (D), the counter normally counts
    --           If True, the counting work is turned off, Add only fills the
    --           LastValue, which can be used as signature, when a counter
    --           works from data which are not available from a Signature
    ---C++ : return &

    Clear (me : mutable)  is virtual;

    Add (me : mutable; ent : Transient; sign : CString);
    ---Purpose : Adds an entity with its signature, i.e. :
    --           - counts an item more for <sign>
    --           - if record-list status is set, records the entity
    --           Accepts a null entity (the signature is then for the global
    --           model). But if the string is empty, counts a Null item.
    --           
    --           If SignOnly Mode is set, this work is replaced by just
    --           setting LastValue

    LastValue (me) returns CString;
    ---Purpose : Returns the last value recorded by Add (only if SignMode set)
    --           Cleared by Clear or Init

    Init (me     : mutable;
    	  name   : CString;
    	  count  : DictionaryOfInteger;
    	  list   : DictionaryOfTransient;
    	  nbnuls : Integer);
    ---Purpose : Aknowledges the list in once. Name identifies the Signature

    List (me; root : CString = "") returns HSequenceOfHAsciiString;
    ---Purpose : Returns the list of signatures, as a sequence of strings
    --           (but without their respective counts). It is ordered.
    --           By default, for all the signatures.
    --           If <root> is given non empty, for the signatures which
    --           begin by <root>

    HasEntities (me) returns Boolean;
    ---Purpose : Returns True if the list of Entities is aknowledged, else
    --           the method Entities will always return a Null Handle

    NbNulls (me) returns Integer;
    ---Purpose : Returns the count of null entities

    NbTimes (me; sign : CString) returns Integer;
    ---Purpose : Returns the number of times a signature was counted,
    --           0 if it has not been recorded at all

    Entities (me; sign : CString) returns HSequenceOfTransient;
    ---Purpose : Returns the list of entities attached to a signature
    --           It is empty if <sign> has not been recorded
    --           It is a Null Handle if the list of entities is not known

    SetName (me : mutable; name : CString);
    ---Purpose : Defines a name for a SignatureList (used to print it)

    Name (me) returns CString  is virtual;
    ---Purpose : Returns the recorded Name.
    --           Remark : default is "..." (no SetName called)

    PrintCount (me; S : Messenger from Message)  is virtual;
    ---Purpose : Prints the counts of items (not the list)

    PrintList  (me; S : Messenger from Message; model : InterfaceModel;
    	            mod : PrintCount = IFSelect_ListByItem)  is virtual;
    ---Purpose : Prints the lists of items, if they are present (else, prints
    --           a message "no list available")
    --           Uses <model> to determine for each entity to be listed, its
    --           number, and its specific identifier (by PrintLabel)
    --           <mod> gives a mode for printing :
    --           - CountByItem : just count (as PrintCount)
    --           - ShortByItem : minimum i.e. count plus 5 first entity numbers
    --           - ShortByItem(D) complete list of entity numbers (0: "Global")
    --           - EntitiesByItem : list of (entity number/PrintLabel from the model)
    --           other modes are ignored

    PrintSum   (me; S : Messenger from Message)  is virtual;
    ---Purpose : Prints a summary
    --           Item which has the greatest count of entities
    --           For items which are numeric values : their count, maximum,
    --           minimum values, cumul, average

fields

    thesignonly : Boolean;
    thelistat   : Boolean;
    thenbnuls   : Integer;
    thename     : HAsciiString;
    thelastval  : AsciiString;
    thedicount  : DictionaryOfInteger;
    thediclist  : DictionaryOfTransient;

end SignatureList;