hyun1024 opened a new pull request, #968: URL: https://github.com/apache/poi/pull/968
<html> <body> <!--StartFragment--><html><head></head><body><h2 data-path-to-node="4" style="font-family: "Google Sans", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Feature(XSLF): Add Methods to Manage Custom Starting Slide Number</h2><p data-path-to-node="5" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">This Pull Request introduces new user-friendly methods within <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">XMLSlideShow</code> to manage the custom starting slide number of a PowerPoint presentation, corresponding to the <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">firstSlideNum</code> attribute in <code style="font-family: "Google Sans Text", sans-serif !important; line- height: 1.15 !important; margin-top: 0px !important;">ppt/presentation.xml</code>.</p><h3 data-path-to-node="6" style="font-family: "Google Sans", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Changes Summary</h3> <li><code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">getFirstSlideNumber()</code>: Retrieves the current starting slide number (default is 1). <li><code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">setFirstSlideNumber(int num)</code>: Sets the custom starting slide number. <li><code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">unsetFirstSlideNumber()</code>: Removes the firstSlideNum attribute, reverting to the default (1). <h3 data-path-to-node="8" style="font-family: "Google Sans", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">🔍 Rationale for Adding High-Level API</h3><p data-path-to-node="9" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Although the underlying XMLBeans class (<code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">org.openxmlformats.schemas.presentationml.x2006.main.CTPresentation</code>) already contains low-level methods to manipulate <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">firstSlideNum</code>, we propose wrapping this functionality in <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important ;">XMLSlideShow</code> for two critical reasons, aligning with POI's core design principles:</p><h4 data-path-to-node="10" style="font-family: "Google Sans", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">1. Abstraction and API Usability</h4><p data-path-to-node="11" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">The first slide number is a standard, user-facing configuration option in Microsoft PowerPoint. Providing a high-level API prevents users from needing to manually retrieve and manipulate the internal <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">CTPresentation</code> object. This promotes cleaner, more readable code and shields developers from complex OOXML schema details.</p><h4 data-path-to-node="12" style="font-family: "Google Sans", sans-seri f !important; line-height: 1.15 !important; margin-top: 0px !important;">2. Enforcing Application Constraints (Data Validation)</h4><p data-path-to-node="13" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">The low-level <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">CTPresentation</code> methods adhere strictly to the general XML Schema definition (allowing any <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">int</code> value), but they <b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">do not</b> enforce the specific constraints required by the PowerPoint application.</p><ul data-path-to-node="14" style="padding-inline-start: 32px; font-fam ily: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="14,0,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Constraint:</b> Microsoft PowerPoint restricts the value of the <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">firstSlideNum</code> attribute to the bounds <b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">[0, 9999]</b>.</p></li><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="14,1,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Official Reference:</b> This restriction is documented in the Microsoft Open Specifications: <b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">MS-OI29500 (Part 1, Section 19.2.1.26, presentation (Presentation))</b>.</p></li></ul><p data-path-to-node="15" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">By implementing <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-to p: 0px !important;">setFirstSlideNumber(int num)</code> at the <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">XMLSlideShow</code> level, POI can validate the input against the <b style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">PowerPoint application constraints</b>. This ensures that the files created by POI are guaranteed to be considered valid and correctly rendered by Microsoft Office, improving data integrity and user experience.</p><h3 data-path-to-node="16" style="font-family: "Google Sans", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Testing</h3><p data-path-to-node="17" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">The feature is covered by new test methods in <code style ="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">TestXSLFSlideShow.java</code> which verify:</p><ul data-path-to-node="18" style="padding-inline-start: 32px; font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="18,0,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Default value and persistence.</p></li><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="18,1,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">S uccessful setting of boundary values (0 and 9999).</p></li><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="18,2,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Correct behavior of <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">unsetFirstSlideNumber()</code>.</p></li><li style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;"><p data-path-to-node="18,3,0" style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin-top: 0px !important;">Validation logic by throwing <code style="font-family: "Google Sans Text", sans-serif !important; line-height: 1.15 !important; margin -top: 0px !important;">IllegalArgumentException</code> for values outside the [0, 9999] range.</p></li></ul></body></html><!--EndFragment--> </body> </html> -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
