src/documentation/content/xdocs/hslf/how-to-shapes.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
  21
  22 <document>
  23     <header>
  24         <title>Busy Developers' Guide to HSLF drawing layer</title>
  25         <authors>
  26             <person email="yegor@dinom.ru" name="Yegor Kozlov" id="CO"/>
  27         </authors>
  28     </header>
  29     <body>
  30         <section><title>Busy Developers' Guide to HSLF drawing layer</title>
  31              <section><title>Index of Features</title>
  32                 <ul>
  33                     <li><link href="#NewPresentation">How to create a new presentation and add new slides to it</link></li>
  34                     <li><link href="#PageSize">How to retrieve or change slide size</link></li>
  35                     <li><link href="#GetShapes">How to get shapes contained in a particular slide</link></li>
  36                     <li><link href="#Shapes">Drawing a shape on a slide</link></li>
  37                     <li><link href="#Pictures">How to work with pictures</link></li>
  38                     <li><link href="#SlideTitle">How to set slide title</link></li>
  39                     <li><link href="#Fill">How to work with slide/shape background</link></li>
  40                     <li><link href="#Bullets">How to create bulleted lists</link></li>
  41                     <li><link href="#Hyperlinks">Hyperlinks</link></li>
  42                     <li><link href="#Tables">Tables</link></li>
  43                     <li><link href="#RemoveShape">How to remove shapes</link></li>
  44                 </ul>
  45             </section>
  46             <section><title>Features</title>
  47                 <anchor id="NewPresentation"/>
  48                 <section><title>New Presentation</title>
  49                   <source>
  50     //create a new empty slide show
  51     SlideShow ppt = new SlideShow();
  52
  53     //add first slide
  54     Slide s1 = ppt.createSlide();
  55
  56     //add second slide
  57     Slide s2 = ppt.createSlide();
  58
  59     //save changes in a file
  60     FileOutputStream out = new FileOutputStream("slideshow.ppt");
  61     ppt.write(out);
  62     out.close();
  63                  </source>
  64                 </section>
  65                 <anchor id="PageSize"/>
  66                 <section><title>How to retrieve or change slide size</title>
  67                     <source>
  68     SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
  69     //retrieve page size. Coordinates are expressed in points (72 dpi)
  70     java.awt.Dimension pgsize = ppt.getPageSize();
  71     int pgx = pgsize.width; //slide width
  72     int pgy = pgsize.height; //slide height
  73
  74     //set new page size
  75     ppt.setPageSize(new java.awt.Dimension(1024, 768));
  76     //save changes
  77     FileOutputStream out = new FileOutputStream("slideshow.ppt");
  78     ppt.write(out);
  79     out.close();
  80                   </source>
  81                 </section>
  82                 <anchor id="GetShapes"/>
  83                 <section><title>How to get shapes contained in a particular slide</title>
  84                   <p>The superclass of all shapes in HSLF is the Shape class - the elemental object that composes a drawing.
  85                     The following pictute shows the class tree of HSLF shapes:
  86                   </p>
  87                   <p>
  88                           <img src="images/hslf_shapes.gif" alt="Class Tree of HSLF Shapes" width="611" height="412"/>
  89                   </p>
  90                   <p>
  91                     The following fragment demonstrates how to iterate over shapes for each slide.
  92                   </p>
  93                     <source>
  94   SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
  95   //get slides
  96   Slide[] slide = ppt.getSlides();
  97   for (int i = 0; i &lt; slide.length; i++){
  98     Shape[] sh = slide[i].getShapes();
  99     for (int j = 0; j &lt; sh.length; j++){
 100       //name of the shape
 101       String name = sh[j].getShapeName();
 102
 103       //shapes's anchor which defines the position of this shape in the slide
 104       java.awt.Rectangle anchor = sh[j].getAnchor();
 105
 106       if (sh[j] instanceof Line){
 107         Line line = (Line)sh[j];
 108         //work with Line
 109       } else if (sh[j] instanceof AutoShape){
 110         AutoShape shape = (AutoShape)sh[j];
 111         //work with AutoShape
 112       } else if (sh[j] instanceof TextBox){
 113         TextBox shape = (TextBox)sh[j];
 114         //work with TextBox
 115       } else if (sh[j] instanceof Picture){
 116         Picture shape = (Picture)sh[j];
 117         //work with Picture
 118       }
 119     }
 120   }
 121                   </source>
 122                 </section>
 123                 <anchor id="Shapes"/>
 124                 <section><title>Drawing a shape on a slide</title>
 125         <warning>
 126     To work with graphic objects HSLF uses Java2D classes
 127     that may throw exceptions if graphical environment is not available. In case if graphical environment
 128     is not available, you must tell Java that you are running in headless mode and
 129     set the following system property: <code> java.awt.headless=true </code>
 130     (either via <code>-Djava.awt.headless=true</code> startup parameter or via <code>System.setProperty("java.awt.headless", "true")</code>).
 131         </warning>
 132                    <p>
 133                      When you add a shape, you usually specify the dimensions of the shape and the position
 134                      of the upper left corner of the bounding box for the shape relative to the upper left
 135                      corner of the slide. Distances in the drawing layer are measured in points (72 points = 1 inch).
 136                    </p>
 137                    <source>
 138   SlideShow ppt = new SlideShow();
 139
 140   Slide slide = ppt.createSlide();
 141
 142   //Line shape
 143   Line line = new Line();
 144   line.setAnchor(new java.awt.Rectangle(50, 50, 100, 20));
 145   line.setLineColor(new Color(0, 128, 0));
 146   line.setLineStyle(Line.LINE_DOUBLE);
 147   slide.addShape(line);
 148
 149   //TextBox
 150   TextBox txt = new TextBox();
 151   txt.setText("Hello, World!");
 152   txt.setAnchor(new java.awt.Rectangle(300, 100, 300, 50));
 153
 154   //use RichTextRun to work with the text format
 155   RichTextRun rt = txt.getTextRun().getRichTextRuns()[0];
 156   rt.setFontSize(32);
 157   rt.setFontName("Arial");
 158   rt.setBold(true);
 159   rt.setItalic(true);
 160   rt.setUnderlined(true);
 161   rt.setFontColor(Color.red);
 162   rt.setAlignment(TextBox.AlignRight);
 163
 164   slide.addShape(txt);
 165
 166   //Autoshape
 167   //32-point star
 168   AutoShape sh1 = new AutoShape(ShapeTypes.Star32);
 169   sh1.setAnchor(new java.awt.Rectangle(50, 50, 100, 200));
 170   sh1.setFillColor(Color.red);
 171   slide.addShape(sh1);
 172
 173   //Trapezoid
 174   AutoShape sh2 = new AutoShape(ShapeTypes.Trapezoid);
 175   sh2.setAnchor(new java.awt.Rectangle(150, 150, 100, 200));
 176   sh2.setFillColor(Color.blue);
 177   slide.addShape(sh2);
 178
 179   FileOutputStream out = new FileOutputStream("slideshow.ppt");
 180   ppt.write(out);
 181   out.close();
 182
 183                   </source>
 184                 </section>
 185                 <anchor id="Pictures"/>
 186                 <section><title>How to work with pictures</title>
 187
 188   <p>
 189   Currently, HSLF API supports the following types of pictures:
 190   </p>
 191   <ul>
 192     <li>Windows Metafiles (WMF)</li>
 193     <li>Enhanced Metafiles (EMF)</li>
 194     <li>JPEG Interchange Format</li>
 195     <li>Portable Network Graphics (PNG)</li>
 196     <li>Macintosh PICT</li>
 197   </ul>
 198
 199                     <source>
 200   SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
 201
 202   //extract all pictures contained in the presentation
 203   PictureData[] pdata = ppt.getPictureData();
 204   for (int i = 0; i &lt; pdata.length; i++){
 205     PictureData pict = pdata[i];
 206
 207     // picture data
 208     byte[] data = pict.getData();
 209
 210     int type = pict.getType();
 211     String ext;
 212     switch (type){
 213       case Picture.JPEG: ext=".jpg"; break;
 214       case Picture.PNG: ext=".png"; break;
 215       case Picture.WMF: ext=".wmf"; break;
 216       case Picture.EMF: ext=".emf"; break;
 217       case Picture.PICT: ext=".pict"; break;
 218       default: continue;
 219     }
 220     FileOutputStream out = new FileOutputStream("pict_"+i + ext);
 221       out.write(data);
 222       out.close();
 223
 224   }
 225
 226   // add a new picture to this slideshow and insert it in a  new slide
 227   int idx = ppt.addPicture(new File("clock.jpg"), Picture.JPEG);
 228
 229   Picture pict = new Picture(idx);
 230
 231   //set image position in the slide
 232   pict.setAnchor(new java.awt.Rectangle(100, 100, 300, 200));
 233
 234   Slide slide = ppt.createSlide();
 235   slide.addShape(pict);
 236
 237   //now retrieve pictures containes in the first slide and save them on disk
 238   slide = ppt.getSlides()[0];
 239   Shape[] sh = slide.getShapes();
 240   for (int i = 0; i &lt; sh.length; i++){
 241     if (sh[i] instanceof Picture){
 242       Picture pict = (Picture)sh[i];
 243       PictureData pictData = pict.getPictureData();
 244       byte[] data = pictData.getData();
 245       int type = pictData.getType();
 246       if (type == Picture.JPEG){
 247         FileOutputStream out = new FileOutputStream("slide0_"+i+".jpg");
 248         out.write(data);
 249         out.close();
 250       } else if (type == Picture.PNG){
 251         FileOutputStream out = new FileOutputStream("slide0_"+i+".png");
 252         out.write(data);
 253         out.close();
 254       }
 255     }
 256   }
 257
 258   FileOutputStream out = new FileOutputStream("slideshow.ppt");
 259   ppt.write(out);
 260   out.close();
 261
 262                     </source>
 263                 </section>
 264                 <anchor id="SlideTitle"/>
 265                 <section><title>How to set slide title</title>
 266                     <source>
 267     SlideShow ppt = new SlideShow();
 268     Slide slide = ppt.createSlide();
 269     TextBox title = slide.addTitle();
 270     title.setText("Hello, World!");
 271
 272     //save changes
 273     FileOutputStream out = new FileOutputStream("slideshow.ppt");
 274     ppt.write(out);
 275     out.close();
 276                   </source>
 277                   <p>
 278                     Below is the equivalent code in PowerPoint VBA:
 279                   </p>
 280                   <source>
 281     Set myDocument = ActivePresentation.Slides(1)
 282     myDocument.Shapes.AddTitle.TextFrame.TextRange.Text = "Hello, World!"
 283                   </source>
 284                 </section>
 285                 <anchor id="Fill"/>
 286                 <section><title>How to modify background of a slide master</title>
 287                     <source>
 288         SlideShow ppt = new SlideShow();
 289         SlideMaster master = ppt.getSlidesMasters()[0];
 290
 291         Fill fill = master.getBackground().getFill();
 292         int idx = ppt.addPicture(new File("background.png"), Picture.PNG);
 293         fill.setFillType(Fill.FILL_PICTURE);
 294         fill.setPictureData(idx);
 295                   </source>
 296                 </section>
 297                 <section><title>How to modify background of a slide</title>
 298                     <source>
 299         SlideShow ppt = new SlideShow();
 300         Slide slide = ppt.createSlide();
 301
 302         //This slide has its own background.
 303         //Without this line it will use master's background.
 304         slide.setFollowMasterBackground(false);
 305         Fill fill = slide.getBackground().getFill();
 306         int idx = ppt.addPicture(new File("background.png"), Picture.PNG);
 307         fill.setFillType(Fill.FILL_PATTERN);
 308         fill.setPictureData(idx);
 309                   </source>
 310                 </section>
 311                 <section><title>How to modify background of a shape</title>
 312                     <source>
 313         SlideShow ppt = new SlideShow();
 314         Slide slide = ppt.createSlide();
 315
 316         Shape shape = new AutoShape(ShapeTypes.Rectangle);
 317         shape.setAnchor(new java.awt.Rectangle(100, 100, 200, 200));
 318         Fill fill = shape.getFill();
 319         fill.setFillType(Fill.FILL_SHADE);
 320         fill.setBackgroundColor(Color.red);
 321         fill.setForegroundColor(Color.green);
 322
 323         slide.addShape(shape);
 324                   </source>
 325                 </section>
 326                 <anchor id="Bullets"/>
 327                 <section><title>How to create bulleted lists</title>
 328                     <source>
 329   SlideShow ppt = new SlideShow();
 330
 331   Slide slide = ppt.createSlide();
 332
 333   TextBox shape = new TextBox();
 334   RichTextRun rt = shape.getTextRun().getRichTextRuns()[0];
 335   shape.setText(
 336           "January\r" +
 337           "February\r" +
 338           "March\r" +
 339           "April");
 340   rt.setFontSize(42);
 341   rt.setBullet(true);
 342   rt.setBulletOffset(0);  //bullet offset
 343   rt.setTextOffset(50);   //text offset (should be greater than bullet offset)
 344   rt.setBulletChar('\u263A'); //bullet character
 345   slide.addShape(shape);
 346
 347   shape.setAnchor(new java.awt.Rectangle(50, 50, 500, 300));  //position of the text box in the slide
 348   slide.addShape(shape);
 349
 350   FileOutputStream out = new FileOutputStream("bullets.ppt");
 351   ppt.write(out);
 352   out.close();
 353                 </source>
 354                 </section>
 355                 <anchor id="Hyperlinks"/>
 356                 <section><title>How to read hyperlinks from a slide show</title>
 357                     <source>
 358     FileInputStream is = new FileInputStream("slideshow.ppt");
 359     SlideShow ppt = new SlideShow(is);
 360     is.close();
 361
 362     Slide[] slide = ppt.getSlides();
 363     for (int j = 0; j &lt; slide.length; j++) {
 364
 365         //read hyperlinks from the text runs
 366         TextRun[] txt = slide[j].getTextRuns();
 367         for (int k = 0; k &lt; txt.length; k++) {
 368             String text = txt[k].getText();
 369             Hyperlink[] links = txt[k].getHyperlinks();
 370             if(links != null) for (int l = 0; l &lt; links.length; l++) {
 371                 Hyperlink link = links[l];
 372                 String title = link.getTitle();
 373                 String address = link.getAddress();
 374                 String substring = text.substring(link.getStartIndex(), link.getEndIndex()-1); //in ppt end index is inclusive
 375             }
 376         }
 377
 378         //in PowerPoint you can assign a hyperlink to a shape without text,
 379         //for example to a Line object. The code below demonstrates how to
 380         //read such hyperlinks
 381         Shape[] sh = slide[j].getShapes();
 382         for (int k = 0; k &lt; sh.length; k++) {
 383             Hyperlink link = sh[k].getHyperlink();
 384             if(link != null)  {
 385                 String title = link.getTitle();
 386                 String address = link.getAddress();
 387             }
 388         }
 389     }
 390                 </source>
 391                 </section>
 392                 <anchor id="Tables"/>
 393                 <section><title>How to create tables</title>
 394                   <source>
 395       //table data
 396       String[][] data = {
 397           {"INPUT FILE", "NUMBER OF RECORDS"},
 398           {"Item File", "11,559"},
 399           {"Vendor File", "300"},
 400           {"Purchase History File", "10,000"},
 401           {"Total # of requisitions", "10,200,038"}
 402       };
 403
 404       SlideShow ppt = new SlideShow();
 405
 406       Slide slide = ppt.createSlide();
 407       //create a table of 5 rows and 2 columns
 408       Table table = new Table(5, 2);
 409       for (int i = 0; i &lt; data.length; i++) {
 410           for (int j = 0; j &lt; data[i].length; j++) {
 411               TableCell cell = table.getCell(i, j);
 412               cell.setText(data[i][j]);
 413
 414               RichTextRun rt = cell.getTextRun().getRichTextRuns()[0];
 415               rt.setFontName("Arial");
 416               rt.setFontSize(10);
 417
 418               cell.setVerticalAlignment(TextBox.AnchorMiddle);
 419               cell.setHorizontalAlignment(TextBox.AlignCenter);
 420           }
 421       }
 422
 423       //set table borders
 424       Line border = table.createBorder();
 425       border.setLineColor(Color.black);
 426       border.setLineWidth(1.0);
 427       table.setAllBorders(border);
 428
 429       //set width of the 1st column
 430       table.setColumnWidth(0, 300);
 431       //set width of the 2nd column
 432       table.setColumnWidth(1, 150);
 433
 434       slide.addShape(table);
 435       table.moveTo(100, 100);
 436
 437       FileOutputStream out = new FileOutputStream("hslf-table.ppt");
 438       ppt.write(out);
 439       out.close();
 440
 441                     </source>
 442                 </section>
 443
 444                 <anchor id="RemoveShape"/>
 445                 <section><title>How to remove shapes from a slide</title>
 446                   <source>
 447
 448         Shape[] shape = slide.getShapes();
 449         for (int i = 0; i &lt; shape.length; i++) {
 450
 451             //remove the shape
 452             boolean ok = slide.removeShape(shape[i]);
 453             if(ok){
 454               //the shape was removed. Do something.
 455             }
 456         }
 457                     </source>
 458                   </section>
 459
 460             </section>
 461         </section>
 462     </body>
 463 </document>