svl/README.md

   1 # Non-Graphical Helper Code (svtools light)
   2
   3 Contains non-graphical helper code for office applications.
   4
   5 Specifically this module does not depend on or use includes from module
   6 vcl. Originally all code in svtools that did not depend on vcl was split
   7 off into this svl ("svtools light") module.
   8
   9 In particular the `SfxItemSet` is a property-bag like container that
  10 stores arbitrary sets of properties for everything from text run
  11 formats, to Chart regression line properties.
  12
  13 There are lots of other useful helpers in here for various office
  14 tasks; much of this code was originally moved from `svx/sfx2`.
  15
  16 ## Items, Pools and Sets
  17
  18 ### SfxPoolItem
  19
  20 A small reference counted piece of data.  Many subclasses, each with a
  21 unique integer to identify its type (`WhichId`).  Can be compared for equality
  22 (`operator==`), `Clone()`d, and converted to/from `uno::Any` (`QueryValue/PutValue`).
  23
  24 A pool item may have value semantics ("poolable"), meaning that
  25 there will generally be only one instance that compares equal per item pool,
  26 or not, in which case the item will be `Clone()`d quite a bit.
  27
  28 ### SfxItemPool
  29
  30 Usually there is one item pool per document, with a range of valid `WhichId`s
  31 that is specific to the type of document.
  32
  33 The item pool owns all instances of `SfxPoolItem` or its subclasses that have
  34 ever been added to an item set.  It also contains a default item for
  35 every WhichId, which will be (depending on parameters) returned from item
  36 sets if the set does not contain an item at this `WhichId`.
  37
  38 ### SfxItemSet
  39
  40 The item set can be created with a user-supplied range of `WhichId`s; it
  41 will accept `SfxPoolItems` with matching `WhichId`s and ignore attempts to
  42 insert items with non-matching `WhichId`s.
  43
  44 Items that are successfully inserted into the set will be stored in the
  45 set's `SfxItemPool`, and for poolable items only a single instance that
  46 compares equal under the predicate `operator==` will be stored in the pool,
  47 regardless of how many sets contain it, thus conserving memory.
  48
  49 There are members `m_pWhichRanges` for the valid ranges (as pairs of `WhichId`s),
  50 `m_nCount` for the number of items contained, and `m_pItems` for the pointers to
  51 the actual items.