In general, the API primitives for document editing fall into three categories: PD_Document -- inbound from import, keyboard, undo/redo PX_ChangeRecord -- at undo granularity PL_Listener -- outbound to views, file export, clipboard For the most part, all of the necessary editing operations for fields can be done without widening any of these APIs. (I'll send another note in a minute about an alternative which would require API mods.) inbound API calls to PD_Document -------------------------------- For example, here's what the API calls from the parser would look like during field import: appendStrux(PTX_Field,...) appendSpan(...) appendFmt(...) appendSpan(...) appendStrux(PTX_FieldEnd,...) As far as editing is concerned, adding a field from the UI is user-atomic: beginUserAtomicGlob() insertStrux(pos, PTX_Field) changeStruxFmt(...) insertSpan(pos,...) insertStrux(pos, PTX_FieldEnd) endUserAtomicGlob() Updating a field's contents is atomic: beginUserAtomicGlob() insertSpan(pos,...) deleteSpan(pos,pos,...) endUserAtomicGlob() NOTE: We may need to play with the ordering here. A user-atomic delete operation which spans the entire field should probably also be coalesced to remove the field boundaries, but since that logic probably belongs in pt_PieceTable::_tweakDeleteSpanOnce(), we want to make sure it doesn't fire in this case. Updating a field's properties is also atomic: beginUserAtomicGlob() changeStruxFmt(...) insertSpan(pos,...) deleteSpan(pos,pos,...) endUserAtomicGlob() By comparison, "normal" editing of a field's contents is trivial, since it should just be an extension of the existing frag-handling logic in the implementations of insertSpan() and deleteSpan(). internal use of PX_ChangeRecord ------------------------------- I'll assert that since we're resuing the existing srtux mechanism, nothing new here is needed. outbound API calls via PL_Listener ---------------------------------- Again, there'll be more calls using the new strux types, which means that there will be more cases to recognize in the listener implementations. However, there shouldn't need to be any new methods or arguments in this API. Paul
