doc: document font properties analysis

doc/developer/analysis/objects/font.rst

@@ -0,0 +1,193 @@
+####
+Font
+####
+
+:Updated:  2013-06-22
+:Author:   Steve Canny
+:Status:   **WORKING DRAFT**
+
+
+Introduction
+============
+
+The ``Font`` object is a descriptively named wrapper for run properties. The
+name was chosen to correspond with the `Font object in the MS API`_.
+
+Font properties from MS API
+===========================
+
+The following properties from the MS API are candidates for inclusion in |pp|.
+
+Implemented
+-----------
+
+Bold
+   Determines whether the character format is bold. Read/write.
+
+Size
+   Returns or sets the character size, in points. Read/write.
+
+
+Backlog
+-------
+
+Caps
+   Gets or sets a value specifying that the text should be capitalized.
+   Read/write. Corresponds to the ``cap`` attribute of the |rPr| element.
+   May be set to MsoTextCaps enumeration values msoNoCaps, msoSmallCaps, or
+   msoAllCaps. Return value may also be msoCapsMixed when more than one run
+   is involved.
+
+Color
+   Returns a ColorFormat object that represents the color for the specified
+   characters. Read-only. Pretty sure this indicates the need for a ``Fill``
+   class, one type of which is ``SolidFill``.
+
+Italic
+   Determines whether the text is italic. Read/write. Corresponds to the
+   ``i`` attribute of the |rPr| element. True, False, or None. When set to
+   None, its value is inherited.
+
+Name
+   Gets or sets a value specifying the font to use for a selection. Read/write.
+   Corresponds to the ``typeface`` attribute of the ``<a:latin>`` child
+   element of |rPr|.
+
+StrikeThrough
+   Gets or sets a value specifying the text should be rendered in
+   a strikethrough appearance. Read/write. Corresponds to the ``strike``
+   attribute of the |rPr| element.
+
+Subscript
+   Gets or sets a value specifying that the selected text should be displayed
+   as subscript. Read/write. Implemented using the ``baseline`` attribute of
+   the |rPr| element, setting it to -25000 (-25%).
+
+Superscript
+   Gets or sets a value specifying that the selected text should be displayed
+   as superscript. Read/write. Implemented using the ``baseline`` attribute
+   of the |rPr| element, setting it to 30000 (30%)
+
+UnderlineStyle
+   Gets or sets a value specifying the underline style for the selected text.
+   Read/write. One of 18 possible values in the MsoTextUnderlineType
+   enumeration.
+
+
+Someday, maybe
+--------------
+
+Allcaps
+   True if the font is formatted as all capital letters. Read/write.
+
+AutorotateNumbers
+   Gets or sets a value that specifies whether the numbers in a numbered list
+   should be rotated when the text is rotated. Read/write.
+
+BaselineOffset
+   Returns or sets the baseline offset for the specified superscript or
+   subscript characters. Read/write. Corresponds to the ``baseline`` attribute
+   of the |rPr| element.
+
+Creator
+   Gets a value indicating the application the object was created in.
+   Read-only.
+
+DoubleStrikeThrough
+   True if the specified font is formatted as double strikethrough text.
+   Read/write.
+
+Emboss
+   Determines whether the character format is embossed. Read/write.
+
+Equalize
+   Gets or sets a value specifying whether the text for a selection should be
+   spaced equal distances apart. Read/write.
+
+Fill
+   Gets the formatting properties for the font of the specified text. Read-only
+
+Glow
+   Gets a value indicating whether the font is displayed as a glow effect.
+   Read-only.
+
+Highlight
+   Gets a value indicating whether the font is displayed as highlighted.
+   Read-only.
+
+Kerning
+   Gets or sets a value specifying the amount of spacing between text
+   characters. Read/write.
+
+Line
+   Gets a value specifiying the format of a line. Read-only.
+
+NameAscii
+   Returns or sets the font used for ASCII characters (characters with
+   character set numbers within the range of 0 to 127). Read/write.
+
+NameComplexScript
+   Returns or sets the complex script font name. Used for mixed language text.
+   Read/write. Corresponds to the ``<a:cs>`` child element of the |rPr|
+   element.
+
+NameFarEast
+   Returns or sets the Asian font name. Read/write.
+
+NameOther
+   Returns or sets the font used for characters whose character set numbers are
+   greater than 127. Read/write.
+
+Reflection
+   Gets a value specifying the type of reflection format for the selection of
+   text. Read-only.
+
+Shadow
+   Gets the value specifying the type of shadow effect for the selection of
+   text. Read-only.
+
+Smallcaps
+   Gets or sets a value specifying whether small caps should be used with the
+   slection of text. Small caps are the same height as the lowercase letters in
+   a slection of text. Read/write.
+
+SoftEdgeFormat
+   Gets or sets a value specifying the type of soft edge effect used in
+   a selection of text. Read/write.
+
+Spacing
+   Gets or sets a value specifying the spacing between characters in
+   a selection of text. Read/write.
+
+Strike
+   Gets or sets a value specifying the strike format used for a selection of
+   text, as in stiking the same character multiple times to make it darker.
+   MsoTextStrike enumeration. Read/write.
+
+UnderlineColor
+   Gets a value specifying the color of the underline for the selected text.
+   Read-only.
+
+WordArtformat
+   Gets or sets a value specifying the text effect for the selected text.
+   Read/write.
+
+
+Mapping UI to API to XML Schema
+===============================
+
+Bold
+   UI: select range of text and press Cmd-B or press Bold icon. API: Set
+   font.bold to True. Schema: ``b`` attribute of ``<a:rPr>`` element.
+
+BaselineOffset
+   UI: Format Text > Font > Offset (%). API: Font.BaselineOffset (float between
+   -1 and 1, representing percentage). Schema: ``baseline`` attribute of
+   ``<a:rPr>`` element (ST_Percentage).
+
+
+.. |rPr| replace:: ``<a:rPr>``
+
+.. _`font object in the MS API`:
+.. _`MSDN Font2 Object API page`:
+   http://msdn.microsoft.com/en-us/library/office/ff863038(v=office.14).aspx

doc/developer/analysis/objects/index.rst

@@ -10,6 +10,7 @@ Collected bits and pieces on specific PowerPoint object types gathered from MSDN
    autoshape
    chart
    coreprops
+   font
    graphicframe
    picture
    placeholder

doc/developer/analysis/schema/ct_textcharacterproperties.rst

@@ -0,0 +1,188 @@
+##############################
+``CT_TextCharacterProperties``
+##############################
+
+.. highlight:: xml
+
+.. csv-table::
+   :header-rows: 0
+   :stub-columns: 1
+   :widths: 25, 50
+
+   Schema Name  , CT_TextCharacterProperties
+   Spec Name    , Text Run Properties
+   Tag(s)       , a:rPr
+   Namespace    , drawingml (dml-main.xsd)
+   Schema Line  , 2907
+   Spec Section , 21.1.2.3.9 rPr (Text Run Properties)
+
+
+Resources
+=========
+
+* ISO-IEC-29500-1, Section 21.1.2.3.9 rPr (Text Run Properties)
+
+
+Spec text
+=========
+
+   This element contains all run level text properties for the text runs within
+   a containing paragraph.
+
+
+Schema excerpt
+==============
+
+::
+
+  <xsd:complexType name="CT_TextCharacterProperties">
+    <xsd:sequence>
+      <xsd:element name="ln"        type="CT_LineProperties" minOccurs="0" maxOccurs="1"/>
+      <xsd:group   ref="EG_FillProperties"                   minOccurs="0" maxOccurs="1"/>
+      <xsd:group   ref="EG_EffectProperties"                 minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="highlight"      type="CT_Color"     minOccurs="0" maxOccurs="1"/>
+      <xsd:group   ref="EG_TextUnderlineLine"                minOccurs="0" maxOccurs="1"/>
+      <xsd:group   ref="EG_TextUnderlineFill"                minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="latin"          type="CT_TextFont"  minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="ea"             type="CT_TextFont"  minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="cs"             type="CT_TextFont"  minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="sym"            type="CT_TextFont"  minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="hlinkClick"     type="CT_Hyperlink" minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="hlinkMouseOver" type="CT_Hyperlink" minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="rtl"            type="CT_Boolean"   minOccurs="0"/>
+      <xsd:element name="extLst"         type="CT_OfficeArtExtensionList" minOccurs="0"  maxOccurs="1"/>
+    </xsd:sequence>
+    <xsd:attribute name="kumimoji"   type="xsd:boolean"             use="optional"/>
+    <xsd:attribute name="lang"       type="s:ST_Lang"               use="optional"/>
+    <xsd:attribute name="altLang"    type="s:ST_Lang"               use="optional"/>
+    <xsd:attribute name="sz"         type="ST_TextFontSize"         use="optional"/>
+    <xsd:attribute name="b"          type="xsd:boolean"             use="optional"/>
+    <xsd:attribute name="i"          type="xsd:boolean"             use="optional"/>
+    <xsd:attribute name="u"          type="ST_TextUnderlineType"    use="optional"/>
+    <xsd:attribute name="strike"     type="ST_TextStrikeType"       use="optional"/>
+    <xsd:attribute name="kern"       type="ST_TextNonNegativePoint" use="optional"/>
+    <xsd:attribute name="cap"        type="ST_TextCapsType"         use="optional"/>
+    <xsd:attribute name="spc"        type="ST_TextPoint"            use="optional"/>
+    <xsd:attribute name="normalizeH" type="xsd:boolean"             use="optional"/>
+    <xsd:attribute name="baseline"   type="ST_Percentage"           use="optional"/>
+    <xsd:attribute name="noProof"    type="xsd:boolean"             use="optional"/>
+    <xsd:attribute name="dirty"      type="xsd:boolean"             use="optional" default="true"/>
+    <xsd:attribute name="err"        type="xsd:boolean"             use="optional" default="false"/>
+    <xsd:attribute name="smtClean"   type="xsd:boolean"             use="optional" default="true"/>
+    <xsd:attribute name="smtId"      type="xsd:unsignedInt"         use="optional" default="0"/>
+    <xsd:attribute name="bmk"        type="xsd:string"              use="optional"/>
+  </xsd:complexType>
+
+  <xsd:group name="EG_FillProperties">
+    <xsd:choice>
+      <xsd:element name="noFill"    type="CT_NoFillProperties"         minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="solidFill" type="CT_SolidColorFillProperties" minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="gradFill"  type="CT_GradientFillProperties"   minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="blipFill"  type="CT_BlipFillProperties"       minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="pattFill"  type="CT_PatternFillProperties"    minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="grpFill"   type="CT_GroupFillProperties"      minOccurs="1" maxOccurs="1"/>
+    </xsd:choice>
+  </xsd:group>
+
+  <xsd:group name="EG_EffectProperties">
+    <xsd:choice>
+      <xsd:element name="effectLst" type="CT_EffectList"      minOccurs="1" maxOccurs="1"/>
+      <xsd:element name="effectDag" type="CT_EffectContainer" minOccurs="1" maxOccurs="1"/>
+    </xsd:choice>
+  </xsd:group>
+
+  <xsd:group name="EG_TextUnderlineLine">
+    <xsd:choice>
+      <xsd:element name="uLnTx" type="CT_TextUnderlineLineFollowText"/>
+      <xsd:element name="uLn"   type="CT_LineProperties" minOccurs="0" maxOccurs="1"/>
+    </xsd:choice>
+  </xsd:group>
+
+  <xsd:group name="EG_TextUnderlineFill">
+    <xsd:choice>
+      <xsd:element name="uFillTx" type="CT_TextUnderlineFillFollowText"/>
+      <xsd:element name="uFill"   type="CT_TextUnderlineFillGroupWrapper"/>
+    </xsd:choice>
+  </xsd:group>
+
+  <xsd:complexType name="CT_TextFont">
+    <xsd:attribute name="typeface"    type="ST_TextTypeface" use="required"/>
+    <xsd:attribute name="panose"      type="s:ST_Panose"     use="optional"/>
+    <xsd:attribute name="pitchFamily" type="ST_PitchFamily"  use="optional" default="0"/>
+    <xsd:attribute name="charset"     type="xsd:byte"        use="optional" default="1"/>
+  </xsd:complexType>
+
+  <xsd:complexType name="CT_Hyperlink">
+    <xsd:sequence>
+      <xsd:element name="snd"    type="CT_EmbeddedWAVAudioFile"   minOccurs="0" maxOccurs="1"/>
+      <xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0" maxOccurs="1"/>
+    </xsd:sequence>
+    <xsd:attribute ref="r:id" use="optional"/>
+      <xsd:attribute name="invalidUrl"     type="xsd:string"  use="optional" default=""/>
+      <xsd:attribute name="action"         type="xsd:string"  use="optional" default=""/>
+      <xsd:attribute name="tgtFrame"       type="xsd:string"  use="optional" default=""/>
+      <xsd:attribute name="tooltip"        type="xsd:string"  use="optional" default=""/>
+      <xsd:attribute name="history"        type="xsd:boolean" use="optional" default="true"/>
+      <xsd:attribute name="highlightClick" type="xsd:boolean" use="optional" default="false"/>
+      <xsd:attribute name="endSnd"         type="xsd:boolean" use="optional" default="false"/>
+  </xsd:complexType>
+
+  <xsd:simpleType name="ST_Panose">
+    <xsd:restriction base="xsd:hexBinary">
+      <xsd:length value="10"/>
+    </xsd:restriction>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_Percentage">
+    <xsd:union memberTypes="ST_PercentageDecimal s:ST_Percentage"/>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_TextCapsType">
+    <xsd:restriction base="xsd:token">
+      <xsd:enumeration value="none"/>
+      <xsd:enumeration value="small"/>
+      <xsd:enumeration value="all"/>
+    </xsd:restriction>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_TextNonNegativePoint">
+    <xsd:restriction base="xsd:int">
+      <xsd:minInclusive value="0"/>
+      <xsd:maxInclusive value="400000"/>
+    </xsd:restriction>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_TextPoint">
+    <xsd:union memberTypes="ST_TextPointUnqualified s:ST_UniversalMeasure"/>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_TextStrikeType">
+    <xsd:restriction base="xsd:token">
+      <xsd:enumeration value="noStrike"/>
+      <xsd:enumeration value="sngStrike"/>
+      <xsd:enumeration value="dblStrike"/>
+    </xsd:restriction>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_TextUnderlineType">
+    <xsd:restriction base="xsd:token">
+      <xsd:enumeration value="none"/>
+      <xsd:enumeration value="words"/>
+      <xsd:enumeration value="sng"/>
+      <xsd:enumeration value="dbl"/>
+      <xsd:enumeration value="heavy"/>
+      <xsd:enumeration value="dotted"/>
+      <xsd:enumeration value="dottedHeavy"/>
+      <xsd:enumeration value="dash"/>
+      <xsd:enumeration value="dashHeavy"/>
+      <xsd:enumeration value="dashLong"/>
+      <xsd:enumeration value="dashLongHeavy"/>
+      <xsd:enumeration value="dotDash"/>
+      <xsd:enumeration value="dotDashHeavy"/>
+      <xsd:enumeration value="dotDotDash"/>
+      <xsd:enumeration value="dotDotDashHeavy"/>
+      <xsd:enumeration value="wavy"/>
+      <xsd:enumeration value="wavyHeavy"/>
+      <xsd:enumeration value="wavyDbl"/>
+    </xsd:restriction>
+  </xsd:simpleType>

doc/developer/analysis/schema/index.rst

@@ -16,6 +16,7 @@ Collected bits and pieces from the XML Schema docs, MSDN web pages, and the ISO/
    ct_slide
    ct_table
    ct_textbody
+   ct_textcharacterproperties
    ct_textparagraph
    miscellaneous