diff options
| -rw-r--r-- | svl/source/items/itempool.cxx | 311 | ||||
| -rw-r--r-- | svl/source/items/itemset.cxx | 635 |
2 files changed, 440 insertions, 506 deletions
diff --git a/svl/source/items/itempool.cxx b/svl/source/items/itempool.cxx index 0638eec43d95..473652bae51e 100644 --- a/svl/source/items/itempool.cxx +++ b/svl/source/items/itempool.cxx @@ -100,7 +100,7 @@ const SfxPoolItem* SfxItemPool::GetPoolDefaultItem( sal_uInt16 nWhich ) const pRet = pImp->mpSecondary->GetPoolDefaultItem( nWhich ); else { - SFX_ASSERT( false, nWhich, "unknown Which-Id - cannot get pool default" ); + SFX_ASSERT( false, nWhich, "unknown WhichId - cannot get pool default" ); pRet = 0; } return pRet; @@ -136,51 +136,39 @@ SfxBroadcaster& SfxItemPool::BC() - +/** + * This is the regular ctor to be used for this class. + * An SfxItemPool instance is initialized, which can manage Items in the + * range from 'nStartWhich' to 'nEndWhich'. + * + * For every one of these WhichIds a static Default must be present in the + * 'pDefaults' array. They start with an SfxPoolItem (with the WhichId + * 'nStartWhich'), are sorted by WhichId and consecutively stored. + * + * 'pItemInfos' is a USHORT array arranged in the same way, which holds + * SlotIds and Flags. These SlotIds can be 0, if the affected Items are + * exclusively used in the Core. + * The flags allow for e.g. enabling value sharing (SFX_ITEM_POOLABLE). + * + * If the Pool is supposed to hold SfxSetItems, the ctor cannot yet contain + * static Defaults. This needs to be done afterwards, using + * @see SfxItemPool::SetDefaults(SfxItemPool**). + * + * @see SfxItemPool::SetDefaults(SfxItemPool**) + * @see SfxItemPool::ReleaseDefaults(SfxPoolItem**,sal_uInt16,sal_Bool) + * @see SfxItemPool::ReldaseDefaults(sal_Bool) + */ SfxItemPool::SfxItemPool ( - const OUString& rName, /* Name des Pools zur Idetifikation - im File-Format */ - sal_uInt16 nStartWhich, /* erste Which-Id des Pools */ - sal_uInt16 nEndWhich, /* letzte Which-Id des Pools */ - const SfxItemInfo* pInfos, /* SID-Map und Item-Flags */ - SfxPoolItem** pDefaults, /* Pointer auf statische Defaults, - wird direkt vom Pool referenziert, - jedoch kein Eigent"umer"ubergang */ - bool bLoadRefCounts /* Ref-Counts mitladen oder auf 1 setzen */ + const OUString& rName, /* Pool name to identify in the file format */ + sal_uInt16 nStartWhich, /* First WhichId of the Pool */ + sal_uInt16 nEndWhich, /* Last WhichId of the Pool */ + const SfxItemInfo* pInfos, /* SID Map and Item flags */ + SfxPoolItem** pDefaults, /* Pointer to static Defaults; + is directly referenced by the Pool, + but no transfer of ownership */ + bool bLoadRefCounts /* Load RefCounts or set to 1? */ ) : - -/* [Beschreibung] - - Der im Normalfall verwendete Konstruktor der Klasse SfxItemPool. Es - wird eine SfxItemPool-Instanz initialisiert, die Items im b"undigen - Which-Bereich von 'nStartWhich' bis 'nEndWhich' verwalten kann. - - F"ur jede dieser Which-Ids mu\s ein statischer Default im Array 'pDefaults' - vorhanden sein, die dort beginnend mit einem <SfxPoolItem> mit der - Which-Id 'nStartWhich' nach Which-Ids sortiert aufeinanderfolgend - eingetragen sein m"ussen. - - 'pItemInfos' ist ein identisch angeordnetes Array von USHORTs, die - Slot-Ids darstellen und Flags. Die Slot-Ids k"onnen 0 sein, wenn die - betreffenden Items ausschlie\slich in der Core verwendet werden. - "Uber die Flags kann z.B. bestimmt werden, ob Value-Sharing - (SFX_ITEM_POOLABLE) stattfinden soll. - - [Anmerkung] - - Wenn der Pool <SfxSetItem>s enthalten soll, k"onnen im Konstruktor noch - keine static-Defaults angegeben werden. Dies mu\s dann nachtr"aglich - mit <SfxItemPool::SetDefaults(SfxItemPool**)> geschehen. - - - [Querverweise] - - <SfxItemPool::SetDefaults(SfxItemPool**)> - <SfxItemPool::ReleaseDefaults(SfxPoolItem**,sal_uInt16,sal_Bool)> - <SfxItemPool::ReldaseDefaults(sal_Bool)> -*/ - pItemInfos(pInfos), pImp( new SfxItemPool_Impl( this, rName, nStartWhich, nEndWhich ) ) { @@ -202,28 +190,20 @@ SfxItemPool::SfxItemPool - +/** + * Copy ctor + * + * @see SfxItemPool::Clone() const +*/ SfxItemPool::SfxItemPool ( - const SfxItemPool& rPool, // von dieser Instanz kopieren - bool bCloneStaticDefaults /* sal_True - statische Defaults kopieren + const SfxItemPool& rPool, // Copy from this instance + bool bCloneStaticDefaults /* true + Copy static Defaults - sal_False - statische Defaults - "ubernehehmen */ + false + Take over static Defaults */ ) : - -/* [Beschreibung] - - Copy-Konstruktor der Klasse SfxItemPool. - - - [Querverweise] - - <SfxItemPool::Clone()const> -*/ - pItemInfos(rPool.pItemInfos), pImp( new SfxItemPool_Impl( this, rPool.pImp->aName, rPool.pImp->mnStart, rPool.pImp->mnEnd ) ) { @@ -239,7 +219,7 @@ SfxItemPool::SfxItemPool pImp->nStoringEnd = pImp->mnEnd; pImp->mbPersistentRefCounts = rPool.pImp->mbPersistentRefCounts; - // Static Defaults "ubernehmen + // Take over static Defaults if ( bCloneStaticDefaults ) { SfxPoolItem **ppDefaults = new SfxPoolItem*[pImp->mnEnd-pImp->mnStart+1]; @@ -254,7 +234,7 @@ SfxItemPool::SfxItemPool else SetDefaults( rPool.pImp->ppStaticDefaults ); - // Pool Defaults kopieren + // Copy Pool Defaults for ( sal_uInt16 n = 0; n <= pImp->mnEnd - pImp->mnStart; ++n ) if ( (*( rPool.pImp->ppPoolDefaults + n )) ) { @@ -262,7 +242,7 @@ SfxItemPool::SfxItemPool (*( pImp->ppPoolDefaults + n ))->SetKind( SFX_ITEMS_POOLDEFAULT ); } - // Copy Version-Map + // Copy Version map for ( size_t nVer = 0; nVer < rPool.pImp->aVersions.size(); ++nVer ) { const SfxPoolVersion_ImplPtr pOld = rPool.pImp->aVersions[nVer]; @@ -270,7 +250,7 @@ SfxItemPool::SfxItemPool pImp->aVersions.push_back( pNew ); } - // Verkettung wiederherstellen + // Repair linkage if ( rPool.pImp->mpSecondary ) SetSecondaryPool( rPool.pImp->mpSecondary->Clone() ); } @@ -279,16 +259,16 @@ SfxItemPool::SfxItemPool void SfxItemPool::SetDefaults( SfxPoolItem **pDefaults ) { - DBG_ASSERT( pDefaults, "erst wollen, dann nichts geben..." ); - DBG_ASSERT( !pImp->ppStaticDefaults, "habe schon defaults" ); + DBG_ASSERT( pDefaults, "first we ask for it, and then we don't give back..." ); + DBG_ASSERT( !pImp->ppStaticDefaults, "already have Defaults" ); pImp->ppStaticDefaults = pDefaults; //! if ( (*ppStaticDefaults)->GetKind() != SFX_ITEMS_STATICDEFAULT ) - //! geht wohl nicht im Zshg mit SetItems, die hinten stehen + //! FIXME: Probably doesn't work with SetItems at the end { DBG_ASSERT( (*pImp->ppStaticDefaults)->GetRefCount() == 0 || IsDefaultItem( (*pImp->ppStaticDefaults) ), - "das sind keine statics" ); + "these are not static" ); for ( sal_uInt16 n = 0; n <= pImp->mnEnd - pImp->mnStart; ++n ) { SFX_ASSERT( (*( pImp->ppStaticDefaults + n ))->Which() == n + pImp->mnStart, @@ -300,71 +280,61 @@ void SfxItemPool::SetDefaults( SfxPoolItem **pDefaults ) } - +/** + * Frees the static Defaults of the corresponding SfxItemPool instance + * and deletes them if specified. + * + * The SfxItemPool instance MUST NOT BE USED after this function has + * been called; only the dtor must be called. + */ void SfxItemPool::ReleaseDefaults ( - bool bDelete /* sal_True - l"oscht sowohl das Array als auch die einzelnen - statischen Defaults + bool bDelete /* true + Deletes the array as well as the single static Defaults - sal_False - l"oscht weder das Array noch die einzelnen - statischen Defaults */ + false + Neither deletes the array not the single static Defaults */ ) -/* [Beschreibung] - - Gibt die statischen Defaults der betreffenden SfxItemPool-Instanz frei - und l"oscht ggf. die statischen Defaults. - - Nach Aufruf dieser Methode darf die SfxItemPool-Instanz nicht mehr - verwendet werden, einzig ist der Aufruf des Destruktors zu"lassig. -*/ { - DBG_ASSERT( pImp->ppStaticDefaults, "keine Arme keine Kekse" ); + DBG_ASSERT( pImp->ppStaticDefaults, "requirements not met" ); ReleaseDefaults( pImp->ppStaticDefaults, pImp->mnEnd - pImp->mnStart + 1, bDelete ); - // KSO (22.10.98): ppStaticDefaults zeigt auf geloeschten Speicher, - // wenn bDelete == sal_True. + // ppStaticDefaults points to deleted memory if bDelete == true. if ( bDelete ) pImp->ppStaticDefaults = 0; } - +/** + * Frees the specified static Defaults und also deletes them, if so + * specified. + * + * This method MUST be called AFTER all SfxItemPool instances (which + * use the specified static Defaults 'pDefault') have been destroyed. + */ void SfxItemPool::ReleaseDefaults ( - SfxPoolItem** pDefaults, /* freizugebende statische Defaults */ + SfxPoolItem** pDefaults, /* Static Defaults that are to be freed */ - sal_uInt16 nCount, /* Anzahl der statischen Defaults */ + sal_uInt16 nCount, /* Count of static Defaults */ - bool bDelete /* sal_True - l"oscht sowohl das Array als auch die - einzelnen statischen Defaults + bool bDelete /* true + Deletes the array as well as the specified + static Defaults - sal_False - l"oscht weder das Array noch die - einzelnen statischen Defaults */ + false + Neither deletes the array nor the single + static Defaults */ ) - -/* [Beschreibung] - - Gibt die angegebenen statischen Defaults frei und l"oscht ggf. - die statischen Defaults. - - Diese Methode darf erst nach Zerst"orung aller SfxItemPool-Instanzen, - welche die angegebenen statischen Defaults 'pDefault' verwenden, - aufgerufen werden. -*/ - { - DBG_ASSERT( pDefaults, "erst wollen, dann nichts geben..." ); + DBG_ASSERT( pDefaults, "we first ask for it and the return nothing ..." ); for ( sal_uInt16 n = 0; n < nCount; ++n ) { SFX_ASSERT( IsStaticDefaultItem( *(pDefaults+n) ), - n, "das ist kein static-default" ); + n, "this is not a static Default" ); (*( pDefaults + n ))->SetRefCount( 0 ); if ( bDelete ) { delete *( pDefaults + n ); *(pDefaults + n) = 0; } @@ -383,9 +353,9 @@ SfxItemPool::~SfxItemPool() if (pImp->mpMaster != NULL && pImp->mpMaster != this) { - // This condition indicates an error. A - // pImp->mpMaster->SetSecondaryPool(...) call should have been made - // earlier to prevent this. At this point we can only try to + // This condition indicates an error. + // A pImp->mpMaster->SetSecondaryPool(...) call should have been made + // earlier to prevent this. At this point we can only try to // prevent a crash later on. DBG_ASSERT( pImp->mpMaster == this, "destroying active Secondary-Pool" ); if (pImp->mpMaster->pImp->mpSecondary == this) @@ -422,22 +392,22 @@ void SfxItemPool::Free(SfxItemPool* pPool) void SfxItemPool::SetSecondaryPool( SfxItemPool *pPool ) { - // ggf. an abgeh"angten Pools den Master zur"ucksetzen + // Reset Master in attached Pools if ( pImp->mpSecondary ) { #ifdef DBG_UTIL - SAL_INFO( "svl.items", "fuer Image, dort gibt es derzeit keine Statics - Bug" ); + SAL_INFO( "svl.items", "for Image: there are not statics; this is a bug" ); if ( pImp->ppStaticDefaults ) { - // Delete() ist noch nicht gelaufen? + // Delete() did not yet run? if ( !pImp->maPoolItems.empty() && !pImp->mpSecondary->pImp->maPoolItems.empty() ) { - // hat der master SetItems? + // Does the Master have SetItems? bool bHasSetItems = false; for ( sal_uInt16 i = 0; !bHasSetItems && i < pImp->mnEnd - pImp->mnStart; ++i ) bHasSetItems = pImp->ppStaticDefaults[i]->ISA(SfxSetItem); - // abgehaengte Pools muessen leer sein + // Detached Pools must be empty bool bOK = bHasSetItems; for ( sal_uInt16 n = 0; bOK && n <= pImp->mpSecondary->pImp->mnEnd - pImp->mpSecondary->pImp->mnStart; @@ -465,13 +435,13 @@ void SfxItemPool::SetSecondaryPool( SfxItemPool *pPool ) p->pImp->mpMaster = pImp->mpSecondary; } - // ggf. den Master der neuen Secondary-Pools setzen - DBG_ASSERT( !pPool || pPool->pImp->mpMaster == pPool, "Secondary tanzt auf zwei Hochzeiten " ); + // Set Master of new Secondary Pools + DBG_ASSERT( !pPool || pPool->pImp->mpMaster == pPool, "Secondary is present in two Pools" ); SfxItemPool *pNewMaster = pImp->mpMaster ? pImp->mpMaster : this; for ( SfxItemPool *p = pPool; p; p = p->pImp->mpSecondary ) p->pImp->mpMaster = pNewMaster; - // neuen Secondary-Pool merken + // Remember new Secondary Pool pImp->mpSecondary = pPool; CHECK_SLOTS(); @@ -529,32 +499,31 @@ SfxItemPool* SfxItemPool::Clone() const void SfxItemPool::Delete() { - // schon deleted? + // Already deleted? if ( pImp->maPoolItems.empty() || !pImp->ppPoolDefaults ) return; - // z.B. laufenden Requests bescheidsagen + // Inform e.g. running Requests pImp->aBC.Broadcast( SfxSimpleHint( SFX_HINT_DYING ) ); - //MA 16. Apr. 97: Zweimal durchlaufen, in der ersten Runde fuer die SetItems. - //Der Klarheit halber wird das jetzt in zwei besser lesbare Schleifen aufgeteilt. - + // Iterate through twice: first for the SetItems. + // We separate this into two loops (for clarity's sake) std::vector<SfxPoolItemArray_Impl*>::iterator itrItemArr = pImp->maPoolItems.begin(); SfxPoolItem** ppDefaultItem = pImp->ppPoolDefaults; SfxPoolItem** ppStaticDefaultItem = pImp->ppStaticDefaults; sal_uInt16 nArrCnt; - //Erst die SetItems abraeumen - SAL_INFO( "svl.items", "fuer Image, dort gibt es derzeit keine Statics - Bug" ); + // Collect the SetItems first + SAL_INFO( "svl.items", "for Image: there are not statics there yet; this is a bug" ); if ( pImp->ppStaticDefaults ) { for ( nArrCnt = GetSize_Impl(); nArrCnt; --nArrCnt, ++itrItemArr, ++ppDefaultItem, ++ppStaticDefaultItem ) { - // KSO (22.10.98): *ppStaticDefaultItem kann im dtor einer - // von SfxItemPool abgeleiteten Klasse bereits geloescht worden - // sein! -> CHAOS Itempool + // *ppStaticDefaultItem could've already been deleted in a class derived + // from SfxItemPool + // This causes chaos in Itempool! if ( *ppStaticDefaultItem && (*ppStaticDefaultItem)->ISA(SfxSetItem) ) { if ( *itrItemArr ) @@ -584,7 +553,7 @@ void SfxItemPool::Delete() itrItemArr = pImp->maPoolItems.begin(); ppDefaultItem = pImp->ppPoolDefaults; - //Jetzt die 'einfachen' Items + // Now for the easy Items for ( nArrCnt = GetSize_Impl(); nArrCnt; --nArrCnt, ++itrItemArr, ++ppDefaultItem ) @@ -635,13 +604,13 @@ void SfxItemPool::SetPoolDefaultItem(const SfxPoolItem &rItem) pImp->mpSecondary->SetPoolDefaultItem(rItem); else { - SFX_ASSERT( false, rItem.Which(), "unknown Which-Id - cannot set pool default" ); + SFX_ASSERT( false, rItem.Which(), "unknown WhichId - cannot set pool default" ); } } -/* - * Resets the default of the given <Which-Id> back to the static default. - * If a pool default exists it is removed. +/** + * Resets the default of the given WhichId back to the static Default. + * If a pool default exists, it is removed. */ void SfxItemPool::ResetPoolDefaultItem( sal_uInt16 nWhichId ) { @@ -659,7 +628,7 @@ void SfxItemPool::ResetPoolDefaultItem( sal_uInt16 nWhichId ) pImp->mpSecondary->ResetPoolDefaultItem(nWhichId); else { - SFX_ASSERT( false, nWhichId, "unknown Which-Id - cannot set pool default" ); + SFX_ASSERT( false, nWhichId, "unknown WhichId - cannot set pool default" ); } } @@ -674,23 +643,23 @@ const SfxPoolItem& SfxItemPool::Put( const SfxPoolItem& rItem, sal_uInt16 nWhich if ( 0 == nWhich ) nWhich = rItem.Which(); - // richtigen Secondary-Pool finden + // Find correct Secondary Pool bool bSID = nWhich > SFX_WHICH_MAX; if ( !bSID && !IsInRange(nWhich) ) { if ( pImp->mpSecondary ) return pImp->mpSecondary->Put( rItem, nWhich ); - OSL_FAIL( "unknown Which-Id - cannot put item" ); + OSL_FAIL( "unknown WhichId - cannot put item" ); } - // SID oder nicht poolable (neue Definition)? + // SID or not poolable (new definition)? sal_uInt16 nIndex = bSID ? USHRT_MAX : GetIndex_Impl(nWhich); if ( USHRT_MAX == nIndex || IsItemFlag_Impl( nIndex, SFX_ITEM_NOT_POOLABLE ) ) { SFX_ASSERT( USHRT_MAX != nIndex || rItem.Which() != nWhich || !IsDefaultItem(&rItem) || rItem.GetKind() == SFX_ITEMS_DELETEONIDLE, - nWhich, "ein nicht Pool-Item ist Default?!" ); + nWhich, "a non Pool Item is Defaul?!" ); SfxPoolItem *pPoolItem = rItem.Clone(pImp->mpMaster); pPoolItem->SetWhich(nWhich); AddRef( *pPoolItem ); @@ -712,7 +681,7 @@ const SfxPoolItem& SfxItemPool::Put( const SfxPoolItem& rItem, sal_uInt16 nWhich bool ppFreeIsSet = false; // Is this a 'poolable' item - ie. should we re-use and return - // the same underlying item for equivalent (==) SfxPoolItems ? + // the same underlying item for equivalent (==) SfxPoolItems? if ( IsItemFlag_Impl( nIndex, SFX_ITEM_POOLABLE ) ) { // if is already in a pool, then it is worth checking if it is in this one. @@ -828,9 +797,9 @@ void SfxItemPool::Remove( const SfxPoolItem& rItem ) "SetItem without ItemSet" ); SFX_ASSERT( !IsPoolDefaultItem(&rItem), rItem.Which(), - "wo kommt denn hier ein Pool-Default her" ); + "where's the Pool Default coming from here?" ); - // richtigen Secondary-Pool finden + // Find correct Secondary Pool const sal_uInt16 nWhich = rItem.Which(); bool bSID = nWhich > SFX_WHICH_MAX; if ( !bSID && !IsInRange(nWhich) ) @@ -840,16 +809,16 @@ void SfxItemPool::Remove( const SfxPoolItem& rItem ) pImp->mpSecondary->Remove( rItem ); return; } - OSL_FAIL( "unknown Which-Id - cannot remove item" ); + OSL_FAIL( "unknown WhichId - cannot remove item" ); } - // SID oder nicht poolable (neue Definition)? + // SID or not poolable (new definition)? sal_uInt16 nIndex = bSID ? USHRT_MAX : GetIndex_Impl(nWhich); if ( bSID || IsItemFlag_Impl( nIndex, SFX_ITEM_NOT_POOLABLE ) ) { SFX_ASSERT( USHRT_MAX != nIndex || !IsDefaultItem(&rItem), rItem.Which(), - "ein nicht Pool-Item ist Default?!" ); + "a non Pool Item is Default?!" ); if ( 0 == ReleaseRef(rItem) ) { SfxPoolItem *pItem = &(SfxPoolItem &)rItem; @@ -858,14 +827,14 @@ void SfxItemPool::Remove( const SfxPoolItem& rItem ) return; } - SFX_ASSERT( rItem.GetRefCount(), rItem.Which(), "RefCount == 0, Remove unmoeglich" ); + SFX_ASSERT( rItem.GetRefCount(), rItem.Which(), "RefCount == 0, Remove impossible" ); - // statische Defaults sind eben einfach da + // Static Defaults are just there if ( rItem.GetKind() == SFX_ITEMS_STATICDEFAULT && &rItem == *( pImp->ppStaticDefaults + GetIndex_Impl(nWhich) ) ) return; - // Item im eigenen Pool suchen + // Find Item in own Pool SfxPoolItemArray_Impl* pItemArr = pImp->maPoolItems[nIndex]; SFX_ASSERT( pItemArr, rItem.Which(), "removing Item not in Pool" ); @@ -885,8 +854,8 @@ void SfxItemPool::Remove( const SfxPoolItem& rItem ) SFX_ASSERT( false, rItem.Which(), "removing Item without ref" ); } - //! MI: Hack, solange wir das Problem mit dem Outliner haben - //! siehe anderes MI-REF + // FIXME: Hack, for as long as we have problems with the Outliner + // See other MI-REF if ( 0 == p->GetRefCount() && nWhich < 4000 ) { DELETEZ(p); @@ -936,17 +905,14 @@ SfxItemPool* SfxItemPool::GetMasterPool() const } #endif +/** + * This method should be called at the master pool, when all secondary + * pools are appended to it. + * + * It calculates the ranges of 'which-ids' for fast construction of + * item-sets, which contains all 'which-ids'. + */ void SfxItemPool::FreezeIdRanges() - -/* [Beschreibung] - - This method should be called at the master pool, when all secondary - pools are appended to it. - - It calculates the ranges of 'which-ids' for fast construction of - item-sets, which contains all 'which-ids'. -*/ - { FillItemIdRanges_Impl( pImp->mpPoolRanges ); } @@ -990,7 +956,7 @@ const SfxPoolItem *SfxItemPool::GetItem2(sal_uInt16 nWhich, sal_uInt32 nOfst) co { if ( pImp->mpSecondary ) return pImp->mpSecondary->GetItem2( nWhich, nOfst ); - SFX_ASSERT( false, nWhich, "unknown Which-Id - cannot resolve surrogate" ); + SFX_ASSERT( false, nWhich, "unknown WhichId - cannot resolve surrogate" ); return 0; } @@ -1011,7 +977,7 @@ sal_uInt32 SfxItemPool::GetItemCount2(sal_uInt16 nWhich) const { if ( pImp->mpSecondary ) return pImp->mpSecondary->GetItemCount2( nWhich ); - SFX_ASSERT( false, nWhich, "unknown Which-Id - cannot resolve surrogate" ); + SFX_ASSERT( false, nWhich, "unknown WhichId - cannot resolve surrogate" ); return 0; } @@ -1048,7 +1014,7 @@ sal_uInt16 SfxItemPool::GetSlotId( sal_uInt16 nWhich, bool bDeep ) const { if ( pImp->mpSecondary && bDeep ) return pImp->mpSecondary->GetSlotId(nWhich); - SFX_ASSERT( false, nWhich, "unknown Which-Id - cannot get slot-id" ); + SFX_ASSERT( false, nWhich, "unknown WhichId - cannot get slot-id" ); return 0; } @@ -1083,22 +1049,19 @@ sal_uInt16 SfxItemPool::GetTrueSlotId( sal_uInt16 nWhich, bool bDeep ) const { if ( pImp->mpSecondary && bDeep ) return pImp->mpSecondary->GetTrueSlotId(nWhich); - SFX_ASSERT( false, nWhich, "unknown Which-Id - cannot get slot-id" ); + SFX_ASSERT( false, nWhich, "unknown WhichId - cannot get slot-id" ); return 0; } return pItemInfos[nWhich - pImp->mnStart]._nSID; } +/** + * You must call this function to set the file format version after + * concatenating your secondary-pools but before you store any + * pool, itemset or item. Only set the version at the master pool, + * never at any secondary pool. + */ void SfxItemPool::SetFileFormatVersion( sal_uInt16 nFileFormatVersion ) - -/* [Description] - - You must call this function to set the file format version after - concatenating your secondary-pools but before you store any - pool, itemset or item. Only set the version at the master pool, - never at any secondary pool. -*/ - { DBG_ASSERT( this == pImp->mpMaster, "SfxItemPool::SetFileFormatVersion() but not a master pool" ); diff --git a/svl/source/items/itemset.cxx b/svl/source/items/itemset.cxx index 5a1e64ab7a58..8b3dc0a0976f 100644 --- a/svl/source/items/itemset.cxx +++ b/svl/source/items/itemset.cxx @@ -809,7 +809,25 @@ void SfxItemSet::SetRanges( const sal_uInt16 *pNewRanges ) } - +/** + * The SfxItemSet takes over exactly those SfxPoolItems that are + * set in rSet and are in their own Which range. All others are removed. + * The SfxItemPool is retained, such that SfxPoolItems that have been + * taken over, are moved from the rSet's SfxItemPool to the SfxItemPool + * of *this. + * + * SfxPoolItems in rSet, for which holds 'IsInvalidItem() == true' are + * taken over as invalid items. + * + * @return bool true + * SfxPoolItems have been taken over + * + * false + * No SfxPoolItems have been taken over, because + * e.g. the Which ranges of SfxItemSets are not intersecting + * or the intersection does not contain SfxPoolItems that are + * set in rSet + */ bool SfxItemSet::Set ( const SfxItemSet& rSet, /* The SfxItemSet, whose SfxPoolItems are @@ -817,41 +835,14 @@ bool SfxItemSet::Set bool bDeep /* true (default) - auch die SfxPoolItems aus den ggf. an - rSet vorhandenen Parents werden direkt - in das SfxItemSet "ubernommen + The SfxPoolItems from the parents that may + be present in rSet, are also taken over into + this SfxPoolItemSet false - die SfxPoolItems aus den Parents von - rSet werden nicht ber"ucksichtigt */ + The SfxPoolItems from the parents of + rSet are not taken into account */ ) - -/** - - Das SfxItemSet nimmt genau die SfxPoolItems an, die auch in - rSet gesetzt sind und im eigenen <Which-Bereich> liegen. Alle - anderen werden entfernt. Der SfxItemPool wird dabei beibehalten, - so da"s die "ubernommenen SfxPoolItems dabei ggf. vom SfxItemPool - von rSet in den SfxItemPool von *this "ubernommen werden. - - SfxPoolItems, f"ur die in rSet IsInvalidItem() == sal_True gilt, - werden als Invalid-Item "ubernommen. - - - [R"uckgabewert] - - bool true - es wurden SfxPoolItems "ubernommen - - false - es wurden keine SfxPoolItems "ubernommen, - da z.B. die Which-Bereiche der SfxItemSets - keine Schnittmenge haben oder in der - Schnittmenge keine SfxPoolItems in rSet - gesetzt sind - -*/ - { bool bRet = false; if ( _nCount ) @@ -874,46 +865,44 @@ bool SfxItemSet::Set return bRet; } - +/** + * This method eases accessing single Items in the SfxItemSet. + * Type checking is done via assertion, which makes client code + * much more readable. + * + * The PRODUCT version returns 0, if the Item found is not of the + * specified class. + * + * @returns 0 if the ItemSet does not contain an Item with the Id 'nWhich' + */ const SfxPoolItem* SfxItemSet::GetItem ( - sal_uInt16 nId, // Slot-Id oder Which-Id des Items - bool bSrchInParent, // sal_True: auch in Parent-ItemSets suchen - TypeId aItemType // != 0 => RTTI Pruefung mit Assertion + sal_uInt16 nId, // SlotId or the Item's WhichId + bool bSrchInParent, // sal_True: also search in Parent ItemSets + TypeId aItemType // != 0 => RTTI check using assertion ) const - -/* [Beschreibung] - - Mit dieser Methode wird der Zugriff auf einzelne Items im - SfxItemSet wesentlich vereinfacht. Insbesondere wird die Typpr"ufung - (per Assertion) durchgef"uhrt, wodurch die Applikations-Sourcen - wesentlich "ubersichtlicher werden. In der PRODUCT-Version wird - eine 0 zur"uckgegeben, wenn das gefundene Item nicht von der - angegebenen Klasse ist. Ist kein Item mit der Id 'nWhich' in dem ItemSet, - so wird 0 zurueckgegeben. -*/ - { - // ggf. in Which-Id umrechnen + // Convert to WhichId sal_uInt16 nWhich = GetPool()->GetWhich(nId); - // ist das Item gesetzt oder bei bDeep==sal_True verf"ugbar? + // Is the Item set or 'bDeep == true' available? const SfxPoolItem *pItem = 0; SfxItemState eState = GetItemState( nWhich, bSrchInParent, &pItem ); if ( bSrchInParent && SFX_ITEM_AVAILABLE == eState && nWhich <= SFX_WHICH_MAX ) pItem = &_pPool->GetDefaultItem(nWhich); + if ( pItem ) { - // stimmt der Typ "uberein? + // Does the type match? if ( !aItemType || pItem->IsA(aItemType) ) return pItem; - // sonst Fehler melden + // Else report error OSL_FAIL( "invalid argument type" ); } - // kein Item gefunden oder falschen Typ gefunden + // No Item of wrong type found return 0; } @@ -922,7 +911,7 @@ const SfxPoolItem* SfxItemSet::GetItem const SfxPoolItem& SfxItemSet::Get( sal_uInt16 nWhich, bool bSrchInParent) const { - // suche den Bereich in dem das Which steht: + // Search the Range in which the Which is located in: const SfxItemSet* pAktSet = this; do { @@ -934,13 +923,13 @@ const SfxPoolItem& SfxItemSet::Get( sal_uInt16 nWhich, bool bSrchInParent) const { if( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { - // in diesem Bereich + // In this Range ppFnd += nWhich - *pPtr; if( *ppFnd ) { if( (SfxPoolItem*)-1 == *ppFnd ) { - //?MI: folgender code ist Doppelt (unten) - SFX_ASSERT(_pPool, nWhich, "kein Pool, aber Status uneindeutig"); + //FIXME: The following code is duplicated further down + SFX_ASSERT(_pPool, nWhich, "no Pool, but status is ambiguous"); //!((SfxAllItemSet *)this)->aDefault.SetWhich(nWhich); //!return aDefault; return _pPool->GetDefaultItem( nWhich ); @@ -955,19 +944,19 @@ const SfxPoolItem& SfxItemSet::Get( sal_uInt16 nWhich, bool bSrchInParent) const #endif return **ppFnd; } - break; // dann beim Parent suchen + break; // Continue with Parent } ppFnd += *(pPtr+1) - *pPtr + 1; pPtr += 2; } } -// bis zum Ende vom Such-Bereich: was nun ? zum Parent, oder Default ?? -// if( !*pPtr ) // bis zum Ende vom Such-Bereich ? +//TODO: Search until end of Range: What are we supposed to do now? To the Parent or Default?? +// if( !*pPtr ) // Until the end of the search Range? // break; } while( bSrchInParent && 0 != ( pAktSet = pAktSet->_pParent )); - // dann das Default vom Pool holen und returnen - SFX_ASSERT(_pPool, nWhich, "kein Pool, aber Status uneindeutig"); + // Get the Default from the Pool and return + SFX_ASSERT(_pPool, nWhich, "no Pool, but status is ambiguous"); const SfxPoolItem *pItem = &_pPool->GetDefaultItem( nWhich ); DBG_ASSERT( !pItem->ISA(SfxSetItem) || 0 != &((const SfxSetItem*)pItem)->GetItemSet(), @@ -975,9 +964,9 @@ const SfxPoolItem& SfxItemSet::Get( sal_uInt16 nWhich, bool bSrchInParent) const return *pItem; } - // Notification-Callback - - +/** + * Notification callback + */ void SfxItemSet::Changed( const SfxPoolItem&, const SfxPoolItem& ) { } @@ -997,22 +986,24 @@ sal_uInt16 SfxItemSet::TotalCount() const } -// behalte nur die Items, die auch in rSet enthalten sein (Wert egal) - +/** + * Only retain the Items that are also present in rSet + * (nevermind their value). + */ void SfxItemSet::Intersect( const SfxItemSet& rSet ) { - DBG_ASSERT(_pPool, "nicht implementiert ohne Pool"); - if( !Count() ) // gar keine gesetzt ? + DBG_ASSERT(_pPool, "Not implemented without Pool"); + if( !Count() ) // None set? return; - // loesche alle Items, die im rSet nicht mehr vorhanden sind + // Delete all Items not contained in rSet if( !rSet.Count() ) { - ClearItem(); // alles loeschen + ClearItem(); // Delete everything return; } - // teste mal, ob sich die Which-Bereiche unterscheiden. + // Test whether the Which Ranges are different bool bEqual = true; sal_uInt16* pWh1 = _pWhichRanges; sal_uInt16* pWh2 = rSet._pWhichRanges; @@ -1028,9 +1019,9 @@ void SfxItemSet::Intersect( const SfxItemSet& rSet ) if( n & 1 ) nSize += ( *(pWh1) - *(pWh1-1) ) + 1; } - bEqual = *pWh1 == *pWh2; // auch die 0 abpruefen + bEqual = *pWh1 == *pWh2; // Also check for 0 - // sind die Bereiche identisch, ist es einfacher zu handhaben ! + // If the Ranges are identical, we can easily process it if( bEqual ) { SfxItemArray ppFnd1 = _aItems; @@ -1039,7 +1030,7 @@ void SfxItemSet::Intersect( const SfxItemSet& rSet ) for( ; nSize; --nSize, ++ppFnd1, ++ppFnd2 ) if( *ppFnd1 && !*ppFnd2 ) { - // aus dem Pool loeschen + // Delete from Pool if( !IsInvalidItem( *ppFnd1 ) ) { sal_uInt16 nWhich = (*ppFnd1)->Which(); @@ -1067,7 +1058,7 @@ void SfxItemSet::Intersect( const SfxItemSet& rSet ) ? GetWhichByPos( aIter.GetCurPos() ) : pItem->Which(); if( SFX_ITEM_UNKNOWN == rSet.GetItemState( nWhich, false ) ) - ClearItem( nWhich ); // loeschen + ClearItem( nWhich ); // Delete if( aIter.IsAtEnd() ) break; pItem = aIter.NextItem(); @@ -1079,10 +1070,10 @@ void SfxItemSet::Intersect( const SfxItemSet& rSet ) void SfxItemSet::Differentiate( const SfxItemSet& rSet ) { - if( !Count() || !rSet.Count() ) // gar keine gesetzt ? + if( !Count() || !rSet.Count() )// None set? return; - // teste mal, ob sich die Which-Bereiche unterscheiden. + // Test whether the Which Ranges are different bool bEqual = true; sal_uInt16* pWh1 = _pWhichRanges; sal_uInt16* pWh2 = rSet._pWhichRanges; @@ -1098,9 +1089,9 @@ void SfxItemSet::Differentiate( const SfxItemSet& rSet ) if( n & 1 ) nSize += ( *(pWh1) - *(pWh1-1) ) + 1; } - bEqual = *pWh1 == *pWh2; // auch die 0 abpruefen + bEqual = *pWh1 == *pWh2; // Also test for 0 - // sind die Bereiche identisch, ist es einfacher zu handhaben ! + // If the Ranges are identical, we can easily process it if( bEqual ) { SfxItemArray ppFnd1 = _aItems; @@ -1109,7 +1100,7 @@ void SfxItemSet::Differentiate( const SfxItemSet& rSet ) for( ; nSize; --nSize, ++ppFnd1, ++ppFnd2 ) if( *ppFnd1 && *ppFnd2 ) { - // aus dem Pool loeschen + // Delete from Pool if( !IsInvalidItem( *ppFnd1 ) ) { sal_uInt16 nWhich = (*ppFnd1)->Which(); @@ -1137,7 +1128,7 @@ void SfxItemSet::Differentiate( const SfxItemSet& rSet ) ? GetWhichByPos( aIter.GetCurPos() ) : pItem->Which(); if( SFX_ITEM_SET == rSet.GetItemState( nWhich, false ) ) - ClearItem( nWhich ); // loeschen + ClearItem( nWhich ); // Delete if( aIter.IsAtEnd() ) break; pItem = aIter.NextItem(); @@ -1147,141 +1138,142 @@ void SfxItemSet::Differentiate( const SfxItemSet& rSet ) } -/* Entscheidungstabelle fuer MergeValue[s] - -Grundsaetze: - 1. Ist der Which-Wert im 1.Set "unknown", dann folgt niemals eine Aktion. - 2. Ist der Which-Wert im 2.Set "unknown", dann gilt er als "default". - 3. Es gelten fuer Vergleiche die Werte der "default"-Items. - -1.-Item 2.-Item Values bIgnoreDefs Remove Assign Add - -set set == sal_False - - - -default set == sal_False - - - -dontcare set == sal_False - - - -unknown set == sal_False - - - -set default == sal_False - - - -default default == sal_False - - - -dontcare default == sal_False - - - -unknown default == sal_False - - - -set dontcare == sal_False 1.-Item -1 - -default dontcare == sal_False - -1 - -dontcare dontcare == sal_False - - - -unknown dontcare == sal_False - - - -set unknown == sal_False 1.-Item -1 - -default unknown == sal_False - - - -dontcare unknown == sal_False - - - -unknown unknown == sal_False - - - - -set set != sal_False 1.-Item -1 - -default set != sal_False - -1 - -dontcare set != sal_False - - - -unknown set != sal_False - - - -set default != sal_False 1.-Item -1 - -default default != sal_False - - - -dontcare default != sal_False - - - -unknown default != sal_False - - - -set dontcare != sal_False 1.-Item -1 - -default dontcare != sal_False - -1 - -dontcare dontcare != sal_False - - - -unknown dontcare != sal_False - - - -set unknown != sal_False 1.-Item -1 - -default unknown != sal_False - - - -dontcare unknown != sal_False - - - -unknown unknown != sal_False - - - - -set set == sal_True - - - -default set == sal_True - 2.-Item 2.-Item -dontcare set == sal_True - - - -unknown set == sal_True - - - -set default == sal_True - - - -default default == sal_True - - - -dontcare default == sal_True - - - -unknown default == sal_True - - - -set dontcare == sal_True - - - -default dontcare == sal_True - -1 - -dontcare dontcare == sal_True - - - -unknown dontcare == sal_True - - - -set unknown == sal_True - - - -default unknown == sal_True - - - -dontcare unknown == sal_True - - - -unknown unknown == sal_True - - - - -set set != sal_True 1.-Item -1 - -default set != sal_True - 2.-Item 2.-Item -dontcare set != sal_True - - - -unknown set != sal_True - - - -set default != sal_True - - - -default default != sal_True - - - -dontcare default != sal_True - - - -unknown default != sal_True - - - -set dontcare != sal_True 1.-Item -1 - -default dontcare != sal_True - -1 - -dontcare dontcare != sal_True - - - -unknown dontcare != sal_True - - - -set unknown != sal_True - - - -default unknown != sal_True - - - -dontcare unknown != sal_True - - - -unknown unknown != sal_True - - - -*/ +/** + * Decision table for MergeValue(s) + * + * Principles: + * 1. If the Which value in the 1st set is "unknown", there's never any action + * 2. If the Which value in the 2nd set is "unknown", it's made the "default" + * 3. For comparisons the values of the "default" Items are take into account + * + * 1st Item 2nd Item Values bIgnoreDefs Remove Assign Add + * + * set set == sal_False - - - + * default set == sal_False - - - + * dontcare set == sal_False - - - + * unknown set == sal_False - - - + * set default == sal_False - - - + * default default == sal_False - - - + * dontcare default == sal_False - - - + * unknown default == sal_False - - - + * set dontcare == sal_False 1st Item -1 - + * default dontcare == sal_False - -1 - + * dontcare dontcare == sal_False - - - + * unknown dontcare == sal_False - - - + * set unknown == sal_False 1st Item -1 - + * default unknown == sal_False - - - + * dontcare unknown == sal_False - - - + * unknown unknown == sal_False - - - + * + * set set != sal_False 1st Item -1 - + * default set != sal_False - -1 - + * dontcare set != sal_False - - - + * unknown set != sal_False - - - + * set default != sal_False 1st Item -1 - + * default default != sal_False - - - + * dontcare default != sal_False - - - + * unknown default != sal_False - - - + * set dontcare != sal_False 1st Item -1 - + * default dontcare != sal_False - -1 - + * dontcare dontcare != sal_False - - - + * unknown dontcare != sal_False - - - + * set unknown != sal_False 1st Item -1 - + * default unknown != sal_False - - - + * dontcare unknown != sal_False - - - + * unknown unknown != sal_False - - - + * + * set set == sal_True - - - + * default set == sal_True - 2nd Item 2nd Item + * dontcare set == sal_True - - - + * unknown set == sal_True - - - + * set default == sal_True - - - + * default default == sal_True - - - + * dontcare default == sal_True - - - + * unknown default == sal_True - - - + * set dontcare == sal_True - - - + * default dontcare == sal_True - -1 - + * dontcare dontcare == sal_True - - - + * unknown dontcare == sal_True - - - + * set unknown == sal_True - - - + * default unknown == sal_True - - - + * dontcare unknown == sal_True - - - + * unknown unknown == sal_True - - - + * + * set set != sal_True 1st Item -1 - + * default set != sal_True - 2nd Item 2nd Item + * dontcare set != sal_True - - - + * unknown set != sal_True - - - + * set default != sal_True - - - + * default default != sal_True - - - + * dontcare default != sal_True - - - + * unknown default != sal_True - - - + * set dontcare != sal_True 1st Item -1 - + * default dontcare != sal_True - -1 - + * dontcare dontcare != sal_True - - - + * unknown dontcare != sal_True - - - + * set unknown != sal_True - - - + * default unknown != sal_True - - - + * dontcare unknown != sal_True - - - + * unknown unknown != sal_True - - - + */ static void MergeItem_Impl( SfxItemPool *_pPool, sal_uInt16 &rCount, const SfxPoolItem **ppFnd1, const SfxPoolItem *pFnd2, bool bIgnoreDefaults ) { assert(ppFnd1 != 0 && "Merging to 0-Item"); - // 1. Item ist default? + // 1st Item is Default? if ( !*ppFnd1 ) { if ( IsInvalidItem(pFnd2) ) - // Entscheidungstabelle: default, dontcare, egal, egal + // Decision table: default, dontcare, doesn't matter, doesn't matter *ppFnd1 = (SfxPoolItem*) -1; else if ( pFnd2 && !bIgnoreDefaults && _pPool->GetDefaultItem(pFnd2->Which()) != *pFnd2 ) - // Entscheidungstabelle: default, set, !=, sal_False + // Decision table: default, set, !=, sal_False *ppFnd1 = (SfxPoolItem*) -1; else if ( pFnd2 && bIgnoreDefaults ) - // Entscheidungstabelle: default, set, egal, sal_True + // Decision table: default, set, doesn't matter, sal_True *ppFnd1 = &_pPool->Put( *pFnd2 ); if ( *ppFnd1 ) ++rCount; } - // 1. Item ist gesetzt? + // 1st Item set? else if ( !IsInvalidItem(*ppFnd1) ) { if ( !pFnd2 ) { - // 2. Item ist default + // 2nd Item is Default if ( !bIgnoreDefaults && **ppFnd1 != _pPool->GetDefaultItem((*ppFnd1)->Which()) ) { - // Entscheidungstabelle: set, default, !=, sal_False + // Decision table: set, default, !=, sal_False _pPool->Remove( **ppFnd1 ); *ppFnd1 = (SfxPoolItem*) -1; } } else if ( IsInvalidItem(pFnd2) ) { - // 2. Item ist dontcare + // 2nd Item is dontcare if ( !bIgnoreDefaults || **ppFnd1 != _pPool->GetDefaultItem( (*ppFnd1)->Which()) ) { - // Entscheidungstabelle: set, dontcare, egal, sal_False - // oder: set, dontcare, !=, sal_True + // Decision table: set, dontcare, doesn't matter, sal_False + // or: set, dontcare, !=, sal_True _pPool->Remove( **ppFnd1 ); *ppFnd1 = (SfxPoolItem*) -1; } } else { - // 2. Item ist gesetzt + // 2nd Item is set if ( **ppFnd1 != *pFnd2 ) { - // Entscheidungstabelle: set, set, !=, egal + // Decision table: set, set, !=, doesn't matter _pPool->Remove( **ppFnd1 ); *ppFnd1 = (SfxPoolItem*) -1; } @@ -1291,10 +1283,10 @@ static void MergeItem_Impl( SfxItemPool *_pPool, sal_uInt16 &rCount, void SfxItemSet::MergeValues( const SfxItemSet& rSet, bool bIgnoreDefaults ) { - // Achtung!!! Bei Aenderungen/Bugfixes immer obenstehende Tabelle pflegen! - DBG_ASSERT( GetPool() == rSet.GetPool(), "MergeValues mit verschiedenen Pools" ); + // WARNING! When making changes/fixing bugs, always update the table above!! + DBG_ASSERT( GetPool() == rSet.GetPool(), "MergeValues with different Pools" ); - // teste mal, ob sich die Which-Bereiche unterscheiden. + // Test if the which Ranges are different bool bEqual = true; sal_uInt16* pWh1 = _pWhichRanges; sal_uInt16* pWh2 = rSet._pWhichRanges; @@ -1310,9 +1302,9 @@ void SfxItemSet::MergeValues( const SfxItemSet& rSet, bool bIgnoreDefaults ) if( n & 1 ) nSize += ( *(pWh1) - *(pWh1-1) ) + 1; } - bEqual = *pWh1 == *pWh2; // auch die 0 abpruefen + bEqual = *pWh1 == *pWh2; // Also check for 0 - // sind die Bereiche identisch, ist es effizieter zu handhaben ! + // If the Ranges match, they are easier to process! if( bEqual ) { SfxItemArray ppFnd1 = _aItems; @@ -1331,7 +1323,7 @@ void SfxItemSet::MergeValues( const SfxItemSet& rSet, bool bIgnoreDefaults ) rSet.GetItemState( nWhich, true, &pItem ); if( !pItem ) { - // nicht gesetzt, also default + // Not set, so default if ( !bIgnoreDefaults ) MergeValue( rSet.GetPool()->GetDefaultItem( nWhich ), bIgnoreDefaults ); } @@ -1353,7 +1345,7 @@ void SfxItemSet::MergeValue( const SfxPoolItem& rAttr, bool bIgnoreDefaults ) const sal_uInt16 nWhich = rAttr.Which(); while( *pPtr ) { - // in diesem Bereich? + // In this Range?? if( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { ppFnd += nWhich - *pPtr; @@ -1375,12 +1367,12 @@ void SfxItemSet::InvalidateItem( sal_uInt16 nWhich ) { if( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { - // in diesem Bereich + // In this Range? ppFnd += nWhich - *pPtr; - if( *ppFnd ) // bei mir gesetzt + if( *ppFnd ) // Set for me { - if( (SfxPoolItem*)-1 != *ppFnd ) // noch nicht dontcare ! + if( (SfxPoolItem*)-1 != *ppFnd ) // Not yet dontcare! { _pPool->Remove( **ppFnd ); *ppFnd = (SfxPoolItem*)-1; @@ -1412,65 +1404,60 @@ sal_uInt16 SfxItemSet::GetWhichByPos( sal_uInt16 nPos ) const nPos = nPos - n; pPtr += 2; } - DBG_ASSERT( false, "Hier sind wir falsch" ); + DBG_ASSERT( false, "We're wrong here" ); return 0; } - +/** + * Saves the SfxItemSet instance to the supplied Stream. + * The surrogates as well as the ones with 'bDirect == true' are saved + * to the stream in the following way: + * + * sal_uInt16 ... Count of the set Items + * Count* _pPool->StoreItem() + * + * @see SfxItemPool::StoreItem() const + * @see SfxItemSet::Load(SvStream&,bool,const SfxItemPool*) + */ SvStream &SfxItemSet::Store ( - SvStream& rStream, // Zielstream f"ur normale Items - bool bDirect // TRUE: Items direkt speicher, FALSE: Surrogate + SvStream& rStream, // Target stream for normal Items + bool bDirect /* true: Save Items directly + false: Surrogates */ ) const - -/* [Beschreibung] - - Speichert die <SfxItemSet>-Instanz in den angegebenen Stream. Dabei - werden die Surrorage der gesetzten <SfxPoolItem>s bzw. ('bDirect==sal_True') - die gesetzten Items selbst wie folgt im Stream abgelegt: - - sal_uInt16 (Count) Anzahl der gesetzten Items - Count* _pPool->StoreItem() siehe <SfxItemPool::StoreItem()const> - - - [Querverweise] - - <SfxItemSet::Load(SvStream&,bool,const SfxItemPool*)> -*/ - { - DBG_ASSERT( _pPool, "Kein Pool" ); + DBG_ASSERT( _pPool, "No Pool" ); DBG_ASSERTWARNING( _pPool == _pPool->GetMasterPool(), "no Master Pool" ); - // Position des Counts merken, um ggf. zu korrigieren + // Remember position of the count (to be able to correct it, if need be) sal_uLong nCountPos = rStream.Tell(); rStream.WriteUInt16( _nCount ); - // wenn nichts zu speichern ist, auch keinen ItemIter aufsetzen! + // If there's nothing to save, don't construct an ItemIter if ( _nCount ) { - // mitz"ahlen wieviel Items tats"achlich gespeichert werden - sal_uInt16 nWrittenCount = 0; // Anzahl in 'rStream' gestreamter Items + // Keep record of how many Items are really saved + sal_uInt16 nWrittenCount = 0; // Count of Items streamed in 'rStream' - // "uber alle gesetzten Items iterieren + // Iterate over all set Items SfxItemIter aIter(*this); for ( const SfxPoolItem *pItem = aIter.FirstItem(); pItem; pItem = aIter.NextItem() ) { - // Item (ggf. als Surrogat) via Pool speichern lassen + // Let Items (if need be as a Surrogate) be saved via Pool DBG_ASSERT( !IsInvalidItem(pItem), "can't store invalid items" ); if ( !IsInvalidItem(pItem) && _pPool->StoreItem( rStream, *pItem, bDirect ) ) - // Item wurde in 'rStream' gestreamt + // Item was streamed in 'rStream' ++nWrittenCount; } - // weniger geschrieben als enthalten (z.B. altes Format) + // Fewer written than read (e.g. old format) if ( nWrittenCount != _nCount ) { - // tats"achlichen Count im Stream ablegen + // Store real count in the stream sal_uLong nPos = rStream.Tell(); rStream.Seek( nCountPos ); rStream.WriteUInt16( nWrittenCount ); @@ -1482,72 +1469,66 @@ SvStream &SfxItemSet::Store } - +/** + * This method loads an SfxItemSet from a stream. + * If the SfxItemPool was loaded without RefCounts the loaded Item + * references are counted, else we assume the they were accounted for + * when loadig the SfxItemPool. + * + * @see SfxItemSet::Store(Stream&,bool) const + */ SvStream &SfxItemSet::Load ( - SvStream& rStream, // Stream, aus dem geladen werden soll + SvStream& rStream, // Stream we're loading from - bool bDirect, /* TRUE - Items werden direkt aus dem Stream - gelesen, nicht "uber Surrogate + bool bDirect, /* true + Items are directly read form the stream + and not via Surrogates - sal_False (default) - Items werden "uber Surrogate gelesen */ + false (default) + Items are read via Surrogates */ - const SfxItemPool* pRefPool /* Pool, der die Surrogate aufl"osen kann - (z.B. zum Einf"ugen von Dokumenten) */ + const SfxItemPool* pRefPool /* Pool that can resolve the Surrogates + (e.g. when inserting documents) */ ) - -/* [Beschreibung] - - Diese Methode l"adt ein <SfxItemSet> aus einem Stream. Falls der - <SfxItemPool> ohne Ref-Counts geladen wurde, werden die geladenen - Item-Referenzen in den Items hochgez"ahlt, ansonsten wird vorausgesetzt, - da\s sie schon beim Laden des SfxItemPools ber"ucksichtigt waren. - - [Querverweise] - - <SfxItemSet::Store(Stream&,bool)const> -*/ - { - DBG_ASSERT( _pPool, "Kein Pool"); - DBG_ASSERTWARNING( _pPool == _pPool->GetMasterPool(), "Kein Master-Pool"); + DBG_ASSERT( _pPool, "No Pool"); + DBG_ASSERTWARNING( _pPool == _pPool->GetMasterPool(), "No Master Pool"); - // kein Ref-Pool => Surrogate mit Pool des ItemSets aufl"osen + // No RefPool => Resolve Surrogates with ItemSet's Pool if ( !pRefPool ) pRefPool = _pPool; - // Anzahl der zu ladenden Items laden und dann ebensoviele Items + // Load Item count and as many Items sal_uInt16 nCount = 0; rStream.ReadUInt16( nCount ); for ( sal_uInt16 i = 0; i < nCount; ++i ) { - // Surrogat/Item laden und (Surrogat) aufl"osen lassen + // Load Surrogate/Item and resolve Surrogate const SfxPoolItem *pItem = _pPool->LoadItem( rStream, bDirect, pRefPool ); - // konnte ein Item geladen oder via Surrogat aufgel"ost werden? + // Did we load an Item or resolve a Surrogate? if ( pItem ) { - // Position f"ur Item-Pointer im Set suchen + // Find position for Item pointer in the set sal_uInt16 nWhich = pItem->Which(); SfxItemArray ppFnd = _aItems; const sal_uInt16* pPtr = _pWhichRanges; while ( *pPtr ) { - // in diesem Bereich? + // In this Range?? if ( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { - // Item-Pointer im Set merken + // Remember Item pointer in the set ppFnd += nWhich - *pPtr; - SFX_ASSERT( !*ppFnd, nWhich, "Item doppelt eingetragen"); + SFX_ASSERT( !*ppFnd, nWhich, "Item is present twice"); *ppFnd = pItem; ++_nCount; break; } - // im Range-Array und Item-Array zum n"achsten Which-Range + // In the range array and Item array to the next Which range ppFnd += *(pPtr+1) - *pPtr + 1; pPtr += 2; } @@ -1561,31 +1542,30 @@ SvStream &SfxItemSet::Load bool SfxItemSet::operator==(const SfxItemSet &rCmp) const { - // besonders schnell zu ermittelnde Werte muessen gleich sein + // Values we can get quickly need to be the same if ( _pParent != rCmp._pParent || _pPool != rCmp._pPool || Count() != rCmp.Count() ) return false; - // Ranges durchzaehlen lassen dauert laenger, muss aber auch gleich sein + // Counting Ranges takes longer; they also need to be the same, however sal_uInt16 nCount1 = TotalCount(); sal_uInt16 nCount2 = rCmp.TotalCount(); if ( nCount1 != nCount2 ) return false; - // sind die Ranges selbst ungleich? + // Are the Ranges themselves unequal? for ( sal_uInt16 nRange = 0; _pWhichRanges[nRange]; nRange += 2 ) if ( _pWhichRanges[nRange] != rCmp._pWhichRanges[nRange] || _pWhichRanges[nRange+1] != rCmp._pWhichRanges[nRange+1] ) { - // dann m"ussen wir die langsame Methode verwenden + // We must use the slow method then SfxWhichIter aIter( *this ); for ( sal_uInt16 nWh = aIter.FirstWhich(); nWh; nWh = aIter.NextWhich() ) { - // wenn die Pointer von poolable Items ungleich sind, - // muessen die Items gleich sein + // If the pointer of the poolable Items are unequal, the Items must match const SfxPoolItem *pItem1 = 0, *pItem2 = 0; if ( GetItemState( nWh, false, &pItem1 ) != rCmp.GetItemState( nWh, false, &pItem2 ) || @@ -1599,17 +1579,17 @@ bool SfxItemSet::operator==(const SfxItemSet &rCmp) const return true; } - // Pointer alle gleich? + // Are all pointers the same? if ( 0 == memcmp( _aItems, rCmp._aItems, nCount1 * sizeof(_aItems[0]) ) ) return true; - // dann werden wir wohl alle einzeln vergleichen muessen + // We need to compare each one separately then const SfxPoolItem **ppItem1 = (const SfxPoolItem**) _aItems; const SfxPoolItem **ppItem2 = (const SfxPoolItem**) rCmp._aItems; for ( sal_uInt16 nPos = 0; nPos < nCount1; ++nPos ) { - // wenn die Pointer von poolable Items ungleich sind, - // muessen die Items gleich sein + // If the pointers of the poolable Items are not the same, the Items + // must match if ( *ppItem1 != *ppItem2 && ( ( !*ppItem1 || !*ppItem2 ) || ( IsInvalidItem(*ppItem1) || IsInvalidItem(*ppItem2) ) || @@ -1660,25 +1640,25 @@ int SfxItemSet::PutDirect(const SfxPoolItem &rItem) const sal_uInt16 nWhich = rItem.Which(); #ifdef DBG_UTIL IsPoolDefaultItem(&rItem) || _pPool->GetSurrogate(&rItem); - // nur Assertion in den callees provozieren + // Only cause assertion in the callees #endif while( *pPtr ) { if( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { - // in diesem Bereich + // In this Range? ppFnd += nWhich - *pPtr; const SfxPoolItem* pOld = *ppFnd; - if( pOld ) // schon einer vorhanden + if( pOld ) // One already present { if( rItem == **ppFnd ) - return sal_False; // schon vorhanden ! + return sal_False; // Already present! _pPool->Remove( *pOld ); } else ++_nCount; - // den neuen eintragen + // Add the new one if( IsPoolDefaultItem(&rItem) ) *ppFnd = &_pPool->Put( rItem ); else @@ -1703,10 +1683,10 @@ SfxAllItemSet::SfxAllItemSet( SfxItemPool &rPool ) aDefault(0), nFree(nInitCount) { - // initial keine Items + // Initially no Items _aItems = 0; - // nInitCount Paare an USHORTs fuer Ranges allozieren + // Allocate nInitCount pairs at USHORTs for Ranges _pWhichRanges = new sal_uInt16[ nInitCount + 1 ]; memset( _pWhichRanges, 0, ( nInitCount + 1 ) * sizeof(sal_uInt16) ); } @@ -1725,161 +1705,150 @@ SfxAllItemSet::SfxAllItemSet(const SfxItemSet &rCopy) - +/** + * Explicitly define this ctor to avoid auto-generation by the compiler. + * The compiler does not take the ctor with the 'const SfxItemSet&'! + */ SfxAllItemSet::SfxAllItemSet(const SfxAllItemSet &rCopy) : SfxItemSet(rCopy), aDefault(0), nFree(0) -/* [Anmerkung] - - Der mu\s sein, da sonst vom Compiler einer generiert wird, er nimmt - nicht den Ctor mit der 'const SfxItemSet&'! -*/ { } - +/** + * This internal function creates a new WhichRanges array, which is copied + * from the 'nOldSize'-USHORTs long 'pUS'. It has new USHORTs at the end instead + * of 'nIncr'. + * The terminating sal_uInt16 with the '0' is neither accounted for in 'nOldSize' + * nor in 'nIncr', but always explicitly added. + * + * @returns the new WhichRanges array (the old 'pUS' is freed) + */ static sal_uInt16 *AddRanges_Impl( sal_uInt16 *pUS, std::ptrdiff_t nOldSize, sal_uInt16 nIncr) - -/* Diese interne Funktion erzeugt ein neues Which-Range-Array, welches von - dem 'nOldSize'-USHORTs langen 'pUS' kopiert wird und hinten an Platz - f"ur 'nIncr' neue USHORTs hat. Das terminierende sal_uInt16 mit der '0' - wird weder in 'nOldSize' noch in 'nIncr' mitgez"ahlt, sondern implizit - hinzugerechnet. - - Das neue Which-Range-Array wird als Returnwert zur"uckgegeben, das alte - 'pUS' freigegeben. -*/ - { - // neues Which-Range-Array anlegen + // Create new WhichRanges array sal_uInt16 *pNew = new sal_uInt16[ nOldSize + nIncr + 1 ]; - // die alten Ranges "ubernehmen + // Take over the old Ranges memcpy( pNew, pUS, nOldSize * sizeof(sal_uInt16) ); - // die neuen auf 0 initialisieren + // Initialize the new one to 0 memset( pNew + nOldSize, 0, ( nIncr + 1 ) * sizeof(sal_uInt16) ); - // das alte Array freigeben + // Free the old array delete[] pUS; return pNew; } - +/** + * This internal function creates a new ItemArray, which is copied from 'pItems', + * but has room for a new ItemPointer at 'nPos'. + * + * @returns the new ItemArray (the old 'pItems' is freed) + */ static SfxItemArray AddItem_Impl(SfxItemArray pItems, sal_uInt16 nOldSize, sal_uInt16 nPos) - -/* Diese interne Funktion erzeugt ein neues ItemArray, welches von 'pItems' - kopiert wird, an der Position 'nPos' jedoch Platz f"ur einen neuen - ItemPointer hat. - - Das neue ItemArray wird als Returnwert zur"uckgegeben, das alte 'pItems' - wird freigegeben. -*/ - { - // neues ItemArray anlegen + // Create new ItemArray SfxItemArray pNew = new const SfxPoolItem*[nOldSize+1]; - // war schon vorher eins da? + // Was there one before? if ( pItems ) { - // alte Items vor nPos kopieren + // Copy all Items before nPos if ( nPos ) memcpy( (void*) pNew, pItems, nPos * sizeof(SfxPoolItem *) ); - // alte Items hinter nPos kopieren + // Copy all Items after nPos if ( nPos < nOldSize ) memcpy( (void*) (pNew + nPos + 1), pItems + nPos, (nOldSize-nPos) * sizeof(SfxPoolItem *) ); } - // neues Item initialisieren + // Initialize new Item *(pNew + nPos) = 0; - // altes ItemArray freigeben + // Free old ItemArray delete[] pItems; return pNew; } - +/** + * Putting with automatic extension of the WhichId with the ID of the Item. + */ const SfxPoolItem* SfxAllItemSet::Put( const SfxPoolItem& rItem, sal_uInt16 nWhich ) - -// Putten mit automatischer Erweiterung der Whichs-Ids um die ID -// des Items. - { - sal_uInt16 nPos = 0; // Position f"ur 'rItem' in '_aItems' + sal_uInt16 nPos = 0; // Position for 'rItem' in '_aItems' const sal_uInt16 nItemCount = TotalCount(); - // erstmal sehen, ob es schon einen passenden Bereich gibt + // Let's see first whether there's a suitable Range already sal_uInt16 *pPtr = _pWhichRanges; while ( *pPtr ) { - // Which-Id liegt in diesem Bereich? + // WhichId is within this Range? if( *pPtr <= nWhich && nWhich <= *(pPtr+1) ) { - // Einfuegen + // Insert nPos += nWhich - *pPtr; break; } - // Position des Items in _aItems mitf"uhren + // Carry over the position of the Item in _aItems nPos += *(pPtr+1) - *pPtr + 1; - // zum n"achsten Bereich + // To the next Range pPtr += 2; } - // Which-Id noch nicht vorhanden? + // WhichId not yet present? if ( !*pPtr ) { - // suchen, ob man sie irgendwo dranpacken kann + // Let's see if we can attach it somewhere pPtr = _pWhichRanges; nPos = 0; while ( *pPtr ) { - // Which-Id liegt exakt vor diesem Bereich? + // WhichId is right before this Range? if ( (nWhich+1) == *pPtr ) { - // Bereich waechst nach unten + // Range grows downwards (*pPtr)--; - // vor erstem Item dieses Bereichs Platz schaffen + // Make room before first Item of this Range _aItems = AddItem_Impl(_aItems, nItemCount, nPos); break; } - // Which-Id liegt exakt hinter diesem Bereich? + // WhichId is right after this Range? else if ( (nWhich-1) == *(pPtr+1) ) { - // Bereich waechst nach oben + // Range grows upwards? (*(pPtr+1))++; - // hinter letztem Item dieses Bereichs Platz schaffen + // Make room after last Item of this Range nPos += nWhich - *pPtr; _aItems = AddItem_Impl(_aItems, nItemCount, nPos); break; } - // Position des Items in _aItems mitf"uhren + // Carry over position of the Item in _aItems nPos += *(pPtr+1) - *pPtr + 1; - // zum n"achsten Bereich + // To the next Range pPtr += 2; } } - // keinen erweiterbaren Bereich gefunden? + // No extensible Range found? if ( !*pPtr ) { - // kein Platz mehr in _pWhichRanges => erweitern + // No room left in _pWhichRanges? => Expand! std::ptrdiff_t nSize = pPtr - _pWhichRanges; if( !nFree ) { @@ -1887,24 +1856,24 @@ const SfxPoolItem* SfxAllItemSet::Put( const SfxPoolItem& rItem, sal_uInt16 nWhi nFree += nInitCount; } - // neuen Which-Range anh"angen + // Attach new WhichRange pPtr = _pWhichRanges + nSize; *pPtr++ = nWhich; *pPtr = nWhich; nFree -= 2; - // Itemarray vergroessern + // Expand ItemArray nPos = nItemCount; _aItems = AddItem_Impl(_aItems, nItemCount, nPos); } - // neues Item in Pool aufnehmen + // Add new Item to Pool const SfxPoolItem& rNew = _pPool->Put( rItem, nWhich ); - // altes Item merken + // Remember old Item bool bIncrementCount = false; const SfxPoolItem* pOld = *( _aItems + nPos ); - if ( reinterpret_cast< SfxPoolItem* >( -1 ) == pOld ) // state "dontcare" + if ( reinterpret_cast< SfxPoolItem* >( -1 ) == pOld ) // state "dontcare" pOld = NULL; if ( !pOld ) { @@ -1914,10 +1883,10 @@ const SfxPoolItem* SfxAllItemSet::Put( const SfxPoolItem& rItem, sal_uInt16 nWhi : nWhich <= SFX_WHICH_MAX ? &_pPool->GetDefaultItem( nWhich ) : 0; } - // neue Item in ItemSet aufnehmen + // Add new Item to ItemSet *(_aItems + nPos) = &rNew; - // Changed Notification versenden + // Send Changed Notification if ( pOld ) { Changed( *pOld, rNew ); @@ -1932,8 +1901,10 @@ const SfxPoolItem* SfxAllItemSet::Put( const SfxPoolItem& rItem, sal_uInt16 nWhi } -// Item disablen, wenn durch ein VoidItem mit dem Which-Wert 0 ausgedrueckt - +/** + * Disable Item + * Using a VoidItem with Which value 0 + */ void SfxItemSet::DisableItem(sal_uInt16 nWhich) { Put( SfxVoidItem(0), nWhich ); |