[WASTE-list] User Defined Data

[Marco Piovanelli]

On Fri, 9 Dec 2005 14:58:27 -0500,
Nancy.Lee at rrd.com (Nancy.Lee at rrd.com) wrote:


>I have been using the 3.0d5 Evaluation Kit for testing.  Certainly a

>tremendous amount of effort has gone into it's development - thank you!

>

>2 questions so far:

>(1) Is there a way to set (or plans to implement) user defined data for a

>character range?


Yes, this feature is already in place, though not documented yet.

WASTE 3.0 lets you define any number of custom attributes and apply
those attributes to any text range.  The new API that enables this
functionality is named WERegisterCustomAttribute(), as is declared
as follows:

EXTERN_API ( OSStatus )
WERegisterCustomAttribute
  (		   WESelector				inAttributeSelector,
								OptionBits				inAttributeOptions,
								ByteCount				 inAttributeValueSize,
								DescType				  inAttributeType,
								WEReference			inWE ) ;

Here's a brief explanation of the parameters:

inAttributeSelector is a four-letter tag of your choice that identifies
your custom attribute.  You may want to avoid tags composed by four
lowercase letters, as these may be used for built-in attributes.

inAttributeValueSize is the byte size of the attribute value, or 0
if the attribute you're defining has a variable size (e.g., it is
a string).  Passing 0 in this parameter effectively disables size
checks.

inAttributeType is the four-letter code for the attribute *type*
(e.g., typeBoolean, typeSInt16, typeSInt32, typeIEEE32BitFloatingPoint,
typeChar, etc.).  This may be used in the future to perform automatic
endian-flipping and coercion between types when reading attributes
from persistent storage.

inAttributeOptions can be a combination of:

    weAttributeIsRuler
    weAttributeIsPersistent
    weAttributeDontExtend

If weAttributeIsRuler bit is set, you're registering a paragraph-level
(ruler) attribute; if it's clear, you're registering a character-level
(style) attribute.

If weAttributeIsPersistent is set, this attribute is to be saved
to persistent storage, so it's encoded in WEst/WEru scraps and in
RTF streams.

By default, custom character-level attributes propagate to the "null"
style, and to new text added at a trailing run boundary, just like
built-in style attributes do.  You can specify weAttributeDontExtend
to disable this automatic propagation.

Once a custom attribute is registered, it can be used in conjunction
with WESetAttributes and WEGetAttributes just like built-in attributes.

For example, here's how you could define and apply a custom attribute
to tag words in a document with their phonetic representation for
Speech Manager purposes:

  const FourCharCode   kPhoneticTag = 'PHON';
  const char *         kSomeText = "Hello Michael, the talking computer";
  const char *         kPhoneticText = "mAYkAXl";

  // register our custom attribute 'PHON'
  err = WERegisterCustomAttribute(kPhoneticTag,
     weAttributeIsPersistent | weAttributeDontExtend,
     0, typeChar, myWE);

  // insert some text
  err = WEPut(0, 0, kSomeText, strlen(kSomeText), kTextEncodingUS_ASCII,
     0, 0, 0, 0, myWE);

  // apply our custom attribute to the word "Michael"
  err = WESetOneAttribute(6, 13, kPhoneticTag, kPhoneticText,
     strlen(kPhoneticText), myWE);


>(2) Is the word underline attribute working?  If so - can  you please tell

>me how to apply it to a selection range.


No, underline styles are not working at the moment.  They are saved
internally, and round-tripped to and from persistent storage (RTF and
proprietary scraps), but they aren't rendered.


                                        -- marco

-- 
It's not the data universe only, it's human conversation.
They want to turn it into a one-way flow that they have entirely
monetized. I look at the collective human mind as a kind of
ecosystem. They want to clear cut it. They want to go into the
rainforest of human thought and mow the thing down.