Patch from Josh Holthaus from bug #53165 - HWPF support for fetching the description (alt text) of a picture

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1332594 13f79535-47bb-0310-9956-ffa450edef68

src/documentation/content/xdocs/status.xml

@@ -34,6 +34,7 @@
 
     <changes>
         <release version="3.9-beta1" date="2012-??-??">
+          <action dev="poi-developers" type="add">53165 - HWPF support for fetching the description (alt text) of a picture</action>
           <action dev="poi-developers" type="fix">48528 - support negative arguments to the DATE() function</action>
           <action dev="poi-developers" type="fix">53092 - allow specifying of a TimeZone to DateUtil.getJavaDate(), for when it is known that a file comes from a different (known) timezone to the current machine</action>
           <action dev="poi-developers" type="fix">53043 - don't duplicate hyperlink relationships when saving XSSF file</action>

src/scratchpad/src/org/apache/poi/hwpf/usermodel/Picture.java

@@ -27,11 +27,16 @@ import java.util.zip.InflaterInputStream;
 
 import org.apache.poi.ddf.EscherBSERecord;
 import org.apache.poi.ddf.EscherBlipRecord;
+import org.apache.poi.ddf.EscherComplexProperty;
+import org.apache.poi.ddf.EscherOptRecord;
+import org.apache.poi.ddf.EscherProperties;
+import org.apache.poi.ddf.EscherProperty;
 import org.apache.poi.ddf.EscherRecord;
 import org.apache.poi.hwpf.model.PICF;
 import org.apache.poi.hwpf.model.PICFAndOfficeArtData;
 import org.apache.poi.util.POILogFactory;
 import org.apache.poi.util.POILogger;
+import org.apache.poi.util.StringUtil;
 
 /**
  * Represents embedded picture extracted from Word Document
@@ -489,6 +494,28 @@ public final class Picture
         return width;
     }
     
+    /**
+     * returns the description stored in the alternative text
+     * 
+     * @return pictue description
+     */
+    public String getDescription()
+    {
+       for(EscherRecord escherRecord : _picfAndOfficeArtData.getShape().getChildRecords()){
+          if(escherRecord instanceof EscherOptRecord){
+             EscherOptRecord escherOptRecord = (EscherOptRecord) escherRecord;
+             for(EscherProperty property : escherOptRecord.getEscherProperties()){
+                if(EscherProperties.GROUPSHAPE__DESCRIPTION == property.getPropertyNumber()){
+                   byte[] complexData = ((EscherComplexProperty)property).getComplexData();
+                   return StringUtil.getFromUnicodeLE(complexData,0,complexData.length/2-1);
+                }
+             }
+          }
+       }
+
+       return null;
+    }
+
     /**
      * tries to suggest extension for picture's file by matching signatures of
      * popular image formats to first bytes of picture's contents

src/scratchpad/testcases/org/apache/poi/hwpf/usermodel/TestPictures.java

@@ -333,4 +333,12 @@ public final class TestPictures extends TestCase {
         assertEquals(PictureType.PNG, p.suggestPictureType());
         assertEquals("png", p.suggestFileExtension());
     }
+    
+    public void testPictureWithAlternativeText() throws Exception {
+        HWPFDocument document = HWPFTestDataSamples.openSampleFile("Picture_Alternative_Text.doc");
+        PicturesTable pictureTable = document.getPicturesTable();
+        Picture picture = pictureTable.getAllPictures().get(0);
+
+        assertEquals("This is the alternative text for the picture.", picture.getDescription());
+    }
 }