[aXSL-commit] SF.net SVN: axsl: [480] trunk/axsl/doc/web/font/index.html
An API for XSL-FO.
Status: Alpha
Brought to you by:
victormote
Menu
▾
▴
[aXSL-commit] SF.net SVN: axsl: [480] trunk/axsl/doc/web/font/index.html
|
From: <vic...@us...> - 2006-04-30 00:56:14
|
Revision: 480 Author: victormote Date: 2006-04-29 17:56:03 -0700 (Sat, 29 Apr 2006) ViewCVS: http://svn.sourceforge.net/axsl/?rev=480&view=rev Log Message: ----------- Bring font doc up-to-date. Modified Paths: -------------- trunk/axsl/doc/web/font/index.html Modified: trunk/axsl/doc/web/font/index.html =================================================================== --- trunk/axsl/doc/web/font/index.html 2006-04-30 00:25:13 UTC (rev 479) +++ trunk/axsl/doc/web/font/index.html 2006-04-30 00:56:03 UTC (rev 480) @@ -35,6 +35,24 @@ <p>Information on this page reflects information about the current aXSL repository.</p> +<p>axslFont implementations provide font-related services to a client +application (<strong>CA</strong>). +The CA requests information, and the axslFont implementation provides it. +Here are the general font-related requests that a document-processing +application might have:</p> + +<ul> + <li>I have a font description. Please provide me with a font object.</li> + <li>I have some text. It <(should | should not) be converted for + (ligatures | small-caps | old-style-figures, etc)>*. Please return the + text that I should use.</li> + <li>I have some text. Please tell me how much ipd space will be needed to place + this text.</li> + <li>I am ready to generate my document. Please tell me which fonts I have + used, and provide the properly subsetted font information that I should + embed in the document.</li> +</ul> + <h2><a name="xsl-fo">XSL-FO Conformance</a></h2> <p>aXSLFont is intended to provide an interface that can be used to build applications conformant to the XSL-FO standard. @@ -95,133 +113,96 @@ </table> <h2><a name="api">API</a></h2> -<p>axslFont follows a client-server architecture. -The client application (<strong>CA</strong>) requests information -and an axslFont implementation provides it. -Here are the general font-related requests that a document-processing -application might have:</p> - -<ul> - <li>I have a font description. Please provide me with a font object.</li> - <li>I have some text. It <(should | should not) be converted for - (ligatures | small-caps | old-style-figures, etc)>*. Please return the - text that I should use.</li> - <li>I have some text. Please tell me how much ipd space will be needed to place - this text.</li> - <li>I am ready to generate my document. Please tell me which fonts I have - used, and provide the properly subsetted font information that I should - embed in the document.</li> -</ul> <p>The following is an overview of the classes and interfaces that are exposed to the CA. -For detailed descriptions of these items, build the javadocs for axslFont by -using the Ant build scripts "javadoc-api" target.</p> +The javadocs should also be consulted as they may contain more detailed +documentation.</p> -<h5>FontServer class</h5> -<ul> - <li>Designed to be a singleton, but can be instantiated multiple times if -necessary (use care). It should be thread-safe, as most font services depend -upon a specific FontConsumer instance, which keeps font usage separate between -the various FontConsumers that might be using the Server at any time.</li> - <li>Resolves font names and returns Font objects to CA.</li> - <li>Can be used to maintain state between documents, to avoid overhead of -finding and parsing commonly-used fonts. (Needs method to allow these to be -flushed).</li> - <li>Wherever a FontServer instance is needed, it can be obtained from the -FontConsumer interface. Therefore, after the FontServer and FontConsumer are -properly configured, the only data item that needs to be passed or cached -on the client side is the FontConsumer implementation.</li> -</ul> +<h5>FontServer</h5> +<p>FontServer is mainly responsible for tracking font resources that are +available to the system and making those resources available to +FontConsumers. +FontServer is instantiated in an implementation-specific manner, so consult +the implementation documentation for details.</p> -<h5>FontConsumer interface</h5> -<ul> - <li>Implemented by a class in the CA. The CA must keep track of which - FontConsumer it is requesting services for. This may be important for - several possible reasons: - <ul> - <li>multi-threading environments</li> - <li>situations where the CA may need to - track more than one collection of Fonts</li> - <li>situations where the Renderer or RenderContext wants finer control - over which fonts it can process</li> - </ul> - For CAs that need none of these, they can avoid the overhead by - creating a singleton with a static method to return the FontConsumer. - </li> - <li>Implemention ideas for CAs wishing to use FontConsumer: Most document -processing systems are - organized in a tree-like fashion, so, unless something more - sophisticated is needed, the CA should stash the FontConsumer reference - at the top of the tree, and provide "get" methods in the nodes - that recursively go up the tree until they get to the top. This avoids - the need to either store a reference to it in every node or to pass it - around amongst the various methods.</li> - <li>Passed to FontServer when requesting a font, so that FontServer can keep - track of which fonts are used by the FontConsumer.</li> - <li>Passed to Font when characters are converted or sized, so that Font can - keep track of which glyphs are used.</li> - <li>Passed to FontServer when the client wants to know what to embed.</li> - <li>Include a method allowing the Consumer to reject fonts it knows it cannot - handle.</li> -</ul> +<h5>FontConsumer</h5> +<p>FontConsumer is responsible for providing FontUse instances as requested, +tracking the fonts used by a document, and tracking the glyph subset used by a +document. +FontConsumer is instantiated in an implementation-specific manner, so consult +the implementation documentation for details. +Care should be taken to instantiate exactly one FontConsumer per document +that is processed. +Otherwise the list of fonts and font subset information will be corrupt.</p> -<h5>Font abstract class</h5> -<ul> - <li>returns metrics information</li> - <li>returns glyph substitution information</li> - <li>returns glyph positioning information</li> -</ul> +<h5>FontUse</h5> +<p>FontUse is a specific Font, as used by a specific FontConsumer, with a +specific encoding, from a specific registration. +It is important to keep FontUse instances distinct by encoding so that the +client application can handle any multiple encodings during rendering. +It is important to keep FontUse instances distinct by registration, because +certain methods are relative to that registration. +For example, the method "nextBolderWeight()" might return a different value +for the same font if it were registered as part of two different font families. +FontUse provides the document-specific, encoding-specific, and +registration-specific glyph metrics, encoding, and embedding information. +FontUse instances are obtained from the FontConsumer "selectFont" methods.</p> +<h5>Font</h5> +<p>Font provides general information about a font's metrics. +Font instances are obtained from the FontUse.getFont() method.</p> + <h2><a name="sample">Sample Code</a></h2> -<p>The following is a simplified high-level view of the API as a whole. -Reference to the javadocs and reference application(s) is recommended for more -detailed information.</p> +<p>Consult your implementation documentation for instructions about +instantiating FontServer and FontConsumer.</p> -<h5>Server Initialization</h5> -<p>The process of initializing the server can be done prior to and separately -from any document processing, so that the FontServer data constructs can be -reused by multiple consumers.</p> -<pre>FontServer fontServer = new FontServer(Logger logger); -fontServer.setBaseFontURL(someURL); -fontServer.setBaseURL(someOtherURL); -fontServer.setup(FontConfigFileURL);</pre> +<h5>Font Selection</h5> +<pre>import org.axsl.font.FontUtility; -<h5>Client/Consumer Initialization</h5> -<p>The registration of FontConsumer implementations could be done in a more lazy -way, but is formalized to try to prevent the client application from -unintentionally using implementations that it does not intend to, thus -potentially losing valuable data. The FontConsumer is roughly analagous to the -document that is being processed.</p> -<pre>fontServer.registerFontConsumer(someFontConsumerImpl);</pre> +... -<h5>Resolve a Font</h5> -<pre>FontServer fontServer = fontConsumer.getFontServer(); -Font font = fontServer.selectFont(fontConsumer, fontFamily, - fontStyle, fontWeight, fontVariant, fontStretch, - fontSize);</pre> +FontConsumer consumer = getFontConsumer(); +int fontSelectionStrategy = FontUtility.foFontSelectionStrategy( + "character-by-character", true); +String[] fontFamily = FontUtility.foFontFamily( + "Helvetica, sans-serif"); +int fontStyle = FontUtility.foFontStyle("italic", true); +int fontWeight = FontUtility.foFontWeight("bold", true); +int fontVariant = FontUtility.foFontVariant("small-caps", true); +int fontStretch = FontUtility.foFontVariant("condensed", true); +// We don't care about font size for scalable fonts +int fontSize = 0; +// This will make sure an "S" can be encoded by the returned font +int aChar = "SomeString".charAt(0); +this.resolvedFont = consumer.selectFontXSL( + fontSelectionStrategy, + fontFamily, + fontStyle, + fontWeight, + fontVariant, + fontStretch, + fontSize, + aChar);</pre> <h5>Use a Font instance</h5> -<p>The following are layout tasks that the client application might want to -perform as it works with text.</p> -<pre>charWidth = font.getCharWidth(fontConsumer, aChar, fontSize, letterSpacing); -wordWidth = font.getWordWidth(fontConsumer, aString, fontSize, letterSpacing);</pre> +<p>The javadocs are probably sufficient to comprehend the various methods in +FontUse and Font. +If additional code samples are needed, please make a request on the mailing +list for assistance.</p> -<h5>Embed Fonts in a PDF document.</h5> -<p>More documentation to come.</p> - -<h5>Cleanup.</h5> -<p>Resources used by your FontConsumer implementation can be freed.</p> -<pre>FontServer fontServer = fontConsumer.getFontServer(); -fontServer.releaseFontConsumer(fontConsumer);</pre> - <h2><a name="font-selection-strategy">Notes on font-selection-strategy</a></h2> -<p>To implement font-selection-strategy="character-by-character".</p> +<p>It is believed that current aXSL methods are sufficient to allow an +application to implement font-selection-strategy="character-by-character".</p> -<p>Regarding font-selection-strategy="auto", the standard appears to provide -this possibility as an option for those with a specific strategy in mind. -We don't currently have such a strategy in mind. -If you would like to see a specific strategy implemented, please contact us on -the user mailing list.</p> +<p>Regarding font-selection-strategy="auto", aXSL provides support only in the +sense that the implementation knows that the client application has requested +it. +Providing support beyond this appears to be beyond the scope of aXSL's mission. +The standard appears to provide the "auto" option for those implementations +with a specific strategy in mind. +It is believed that implementations are able to add support for other +strategies within the current aXSL framework. +These strategies would of course be implementation-dependent.</p> <h2><a name="simulated-small-caps">Notes on simulated small-caps</a></h2> <p>Simulated small-caps must be handled outside of the font system. @@ -250,17 +231,13 @@ about this DTD.</p> <h2><a name="charset">Character Set</a></h2> +<p>Because aXSL interfaces use 32-bit int representations for characters, +the entire 21-bit extended Unicode character set is supported. +Here are some useful links regarding this issue:</p> <ul> - <li>Unicode 4.0 compatibility. -The aXSL interfaces use 32-bit int representations for characters, providing -room for the 21-bit Unicode 4.0 extended character set. -Here are some useful links regarding this issue: - <ul> - <li><a + <li><a href="http://java.sun.com/developer/technicalArticles/Intl/Supplementary/">Supplementary Characters in the Java Platform</a></li> - </ul> - </li> </ul> <h2><a name="implementations">Known Implementations</a></h2> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
