fldigigal: Package for creating a Flash Digital Gallery

D. P. Story

                Email: dpstory@uakron.edu

processed January 7, 2011

Contents

1 Introduction  1
2 Implementation  1
2.1 Main Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1 ⟨∗package⟩

 2 \RequirePackage{xkeyval}
 3 \RequirePackage{rmannot}[2010/12/22]

1 Introduction

2 Implementation

This package offers the L^{A}TEX/Distiller user the ability to create Flash Photo Galleries. There are several photo gallery layouts to select from, and some dynamic options that can be specified. The digital photographs (JPG, PNG, or GIF) may be embedded in the PDF document, or may reside online and referenced by an URL.

\fdgFolder The path to the folder containing the the SWF files of this distribution. This path is set through the fldigigal.cfg file.

 4 \newcommand{\fdgFolder}{C:/Users/Public/Documents/My TeX Files/%
 5  tex/latex/aeb/aebpro/fldigigal/swf}

We input the file fldigigal.cfg which should contain a re-definition of the command \fdgFolder, the path to the Flash Digital Gallery SWFs.

 6 \InputIfFileExists{fldigigal.cfg}{}{}

2.1 Main Code

In this section we define the \fdgXmlList and \fgRmAnnot, and their supporting cast of characters.

An internal command for getting the rma object based on the current page and the name of the annot.

 7 \def\fdg@namegdef#1{\expandafter\gdef\csname #1\endcsname}
 8 \def\fdg@namexdef#1{\expandafter\xdef\csname #1\endcsname}

We define \fdg@iso, which, within the \image command, we declare that \let\iso\fdg@iso, defining the \iso command to enter special characters in the caption attribute.

 9 {\catcode`\#=12 \catcode`\&=12 \catcode`\!=6
10  \gdef\fdg@iso!1{&#!1;}

11 }

\fdgXmlList The \fdgXmlList command describes the photos to be displayed in the digital gallery. Here is an example of the structure:

\fdgXmlList[showcount]{myDigis}{%
    \image{path=\myPhotosLocal/Chrysanthemum.jpg,caption=Chrysanthemum}
    \image{path=\myPhotosLocal/Desert.jpg,caption=Desert}
    \image{path=\myPhotosOnline/Hydrangeas.jpg,caption=Hydrangeas,online}
    \image{path=\myPhotosOnline/Jellyfish.jpg,caption=Jellyfish,online}
    \image{path=\myPhotosOnline/Koala.jpg,caption=Koala,online}
    \image{path=\myPhotosOnline/Lighthouse.jpg,caption=Lighthouse,online}
    \image{path=\myPhotosOnline/Penguins.jpg,caption=Penguins,online}
    \image{path=\myPhotosOnline/Tulips.jpg,caption=Tulips,online}
}

The first optional argument takes any optional arguments; at this time, the only option is showcount, where the photo number and total number of photos is displayed, e.g. (2 of 8). The default is not to show the count. The second parameter is the unique name of the gallery. The third parameter consists of any number of image specifications. The \image command has three properties: path, caption, and online. These are describe in more detail below.

path The absolute path (url) to the photo; the path may be on a local hard drive, or on the Internet. Paths may (should) be defined using the the \definePath, defined in the eforms package.

   \definePath{\myPhotosOnline}{%
        http://www.math.uakron.edu/~dpstory/photos/pa_demo}
   \definePath{\myPhotosLocal}{%
        C:/Users/Public/Pictures/Sample Pictures}
12 \define@key{fdgxml}{path}[]{\def\fdg@pa@path{#1}}

caption A (short) string that describes the photo. If the caption key is not present, the filename of the digital photo is used.

13 \define@key{fdgxml}{caption}[]{\def\fdg@pa@caption{#1}}

online A Boolean key, which if true, signals that the path to the photo is on the Internet (http://). If the online key is not present, the path is assumed to be local, and the photo will be embedded in the PDF.

14 \define@boolkey{fdgxml}{online}[true]{}

We set the global defaults of these key-value pairs.

15 \setkeys{fdgxml}{path,caption,online=false}

We use this counter to count the digis as they are defined by the \image macro.

16 \newcount\cntdigis

\image There are two definitions of the \image command: \fdg@cnt@images and

\fdg@image.

\fdg@cnt@images counts the number of images.

17 \def\fdg@cnt@images#1{\advance\cntdigis1 }

\fdg@image does all the work in writing the photo information to an XML file.

18 \def\fdg@image#1{\begingroup
19  \let\Name\rma@resource\let\urlName\rma@urlresource
20  \setkeys{fdgxml}{#1}%
21  \global\advance\cntdigis1

We expand the internal name of the digital resource. The name has the form

Im<number>(<name>).
22  \edef\@digiImgName{Im\the\cntdigis(\fdg@CurrDigiName)}%

Use \saveNamedPath to save this name and path.

23  \saveNamedPath{\@digiImgName}{\fdg@pa@path}%

Get the basename and extension using the \Name command.

24  \edef\fdg@NamedExp{\expandafter\Name\expandafter{\@digiImgName}}%

If the caption is empty, use the basename.ext

25  \ifx\fdg@pa@caption\@empty\def\fdg@pa@caption{\fdg@NamedExp}\fi

If online is true, write the full url path to the xml using the \urlName macro.

26  \ifKV@fdgxml@online
27  \edef\fdg@urlNamedExp{%
28  \expandafter\urlName\expandafter{\@digiImgName}}%
29  \fdg@IWVO{\space\space\space\space
30  <image title='\fdg@pa@caption\fdg@cntOf{\the\cntdigis}'>%
31  \fdg@urlNamedExp</image>
32  }%
33  \else

If online is not listed, or is set to false we embed. We accumulate all resources

that are embedded in \fdg@embededResources
34  \toks0=\expandafter{\fdg@embededResources}%
35  \ifx\fdg@embededResources\@empty
36  \xdef\fdg@embededResources{\@digiImgName}\else
37  \xdef\fdg@embededResources{\the\toks0,\@digiImgName}\fi
38  \fdg@IWVO{\space\space\space\space

39  <image title='\fdg@pa@caption\fdg@cntOf{\the\cntdigis}'>%
40  \fdg@NamedExp</image>
41  }%
42  \fi
43 \endgroup}

Convenience macro for writing to the XML file

44 \def\fdg@IWVO{\immediate\write\verbatim@out}

A (internal) interface to the digi resources. The one argument is the name of the gallery these digis are associated with.

45 \def\embededResources#1{\csname #1ERs\endcsname}

The internal name of the xmlList. The argument is the name of the gallery.

46 \def\xmlListiv#1{xmlList4#1}

\fdgcntOf The internal command for writing the photo count is \fdg@cntOf. Initially, we

\let \fdg@cntOf to \@gobble
47 \let\fdg@cntOf\@gobble
48 \newcommand{\fdgcntOf}[1]{\space(#1 of \fdg@numDigis)}

The options of \fdgXmlList. If true the photo number is displayed, if false, the default, no photo number is displayed.

showcount When the showcount option is specified, we \let \fdg@cntOf to \fdgcntOf.

The command may be redefined. The first argument is the photo number, the command \fdg@numDigis expands to the total number of photos.

49 \define@boolkey{fdgXML}{showcount}[true]{%
50  \ifKV@fdgXML@showcount\let\fdg@cntOf\fdgcntOf\else
51  \let\fdg@cntOf\@gobble\fi

52 }

nowrite When we set this switch, we \let \fdg@IWVO to \@gobble, and do not open a

\newwrite stream.
53 \define@boolkey{fdgXML}{nowrite}[true]{}

Set the defaults for he \fdgXML family.

54 \setkeys{fdgXML}{showcount=false,nowrite=false}

Finally, we have the definition of \fdgXmlList.

55 \newcommand{\fdgXmlList}[3][]{%
56 \begingroup
57  \setkeys{fdgXML}{#1}%
58  \ifKV@fdgXML@nowrite\let\fdg@IWVO\@gobble\fi
59  \cntdigis=0 \gdef\fdg@embededResources{}%
60  \ifKV@fdgXML@nowrite\else
61  \newwrite \fdg@writexmllist
62  \immediate\openout \fdg@writexmllist=#2.xml
63  \let\verbatim@out\fdg@writexmllist
64  \fi

Open he photos xml file and write the top level

65  \fdg@IWVO{<photos>}%
66  \@ifundefined{#2@fdgdigis}{%
67  \fdg@namegdef{#2@fdgdigis}{#2}%
68  \def\fdg@CurrDigiName{#2}%
69  }{\PackageError{fldigigal}{Name already chosen}}%

The #3 parameter contains the \image listing. we first count the number of images

using \fdg@cnt@images.
70  \let\image\fdg@cnt@images#3%
71  \edef\fdg@numDigis{\the\cntdigis}%

Now, we repeat, but this time with \fdg@image.

72  \def\'{&apos;}\let\iso\fdg@iso
73  \cntdigis=0 \let\image\fdg@image#3%

Close out XML List

74  \fdg@IWVO{</photos>}%
75  \ifKV@fdgXML@nowrite\else
76  \immediate\closeout \fdg@writexmllist
77  \fi
78 \endgroup

Save the path to the newly created xml list under the name xmlList4<name>

79  \saveNamedPath{xmlList4#2}{\pathToSource/#2.xml}%

Define a command to save the embedded resources.

80  \fdg@namexdef{#2ERs}{\ifx\fdg@embededResources\@empty\else,\fi
81  \fdg@embededResources}%

82 }

83 \@onlypreamble{\fdgXmlList}

\fgRmannot This is the command that actually places the SWF. It uses the \rmAnnot command from the rmannot package.

Define Key-Value Pairs. We declare two keys for \fgRmannot: gallery and flashvars. We use gallery to select the gallery (layout), and flashvars to set some basic parameters of the SWF.

84 \define@key{fgRmAnnot}{flashvars}[]{\def\fgRmAnnot@flashvars{&#1}}
85 \let\fgRmAnnot@flashvars\@empty
86 \define@key{fgRmAnnot}{galleryopts}[]{\def\fgRmAnnot@galleryopts{#1}}

The ‘\saveNamePath’ definitions for the three supported galleries. I have a custom gallery for no apparent reason (actually, if I want to create and test a new gallery, I can set it up to use the custom key.

87 \saveNamedPath{fdg_vt1}{\fdgFolder/fdg_vt1.swf}
88 \saveNamedPath{fdg_ht1}{\fdgFolder/fdg_ht1.swf}
89 \saveNamedPath{fdg_nt1}{\fdgFolder/fdg_nt1.swf}
90 \saveNamedPath{custom}{\fdgFolder/fdg_vt1.swf}

fgGalleryOpts keys. We now define the key value pairs for the fgGalleryOpts family. These are the keys as listed by galleryopts.

gallery At this time, we offer four choices for a design, more to follow as I learn more about Flash Pro CS5.

 91 \define@choicekey+{fgGalleryOpts}{gallery}[\val\nr]%
 92  {vthumbs1,hthumbs1,nothumbs1,custom}[vthumbs1]{%
 93  \ifcase\nr\relax
 94  \def\fgGalleryOpts@gallery{fdg_vt1}\or
 95  \def\fgGalleryOpts@gallery{fdg_ht1}\or
 96  \def\fgGalleryOpts@gallery{fdg_nt1}\or
 97  \def\fgGalleryOpts@gallery{custom}\fi
 98 }{}

trans Some standard transitions for the photos.

 99 \define@choicekey+{fgGalleryOpts}{trans}[\val\nr]%
100  {Blinds,Fade,Fly,Iris,Photo,PixelDissolve,Rotate,%
101  Squeeze,Wipe,Zoom,Random}[Random]{%
102  \edef\fgGalleryOpts@trans{\val}%
103 }{}
104 \let\fgGalleryOpts@trans\@empty

delay The amount of delay between the automatic display of a new photo. The default is 6 (seconds)

105 \define@key{fgGalleryOpts}{delay}[6]{\def\fgGalleryOpts@delay{#1}}
106 \let\fgGalleryOpts@delay\@empty

auto A Boolean switch, which if true, the photos are displayed automatically, the delay is determined by the delay key. The default is auto=true.

107 \define@boolkey{fgGalleryOpts}{auto}[true]{%
108  \edef\fgGalleryOpts@auto{\ifKV@fgGalleryOpts@auto
109  true\else false\fi}}

transOn A Boolean switch, which if true, a transition effect is used to transition between photos.

110 \define@boolkey{fgGalleryOpts}{transOn}[true]{%
111  \edef\fgGalleryOpts@transOn{\ifKV@fgGalleryOpts@transOn
112  true\else false\fi}}

captionalign For all galleries except for fdg nt1 we can align the position of the caption: left, right, or center. The default is left.

113 \define@choicekey+{fgGalleryOpts}{captionalign}[\val\nr]%
114  {left,right,center}[left]{%
115  \edef\fgGalleryOpts@captionalign{\val}%
116 }{}
117 \let\fgGalleryOpts@captionalign\@empty

nocaptions A Boolean switch, which if true, no caption is written the the caption bar. The default is false, captions are written.

118 \define@boolkey{fgGalleryOpts}{nocaptions}[true]{%
119  \edef\fgGalleryOpts@nocaptions{\ifKV@fgGalleryOpts@nocaptions
120  true\else false\fi}}

nocaptionstext If nocaptions is set to true, the value of this key is used as the caption for all the photos. If nocaptionstext is not listed, or has not value, the empty string is used.

121 \define@key{fgGalleryOpts}{nocaptionstext}[]{%
122  \def\fgGalleryOpts@nocaptionstext{#1}}

Global defaults for the fgGalleryOpts family.

123 \setkeys{fgGalleryOpts}{gallery,transOn,auto=true,nocaptions=false,nocaptionstext}

\fgRmAnnot Now for the definition of \fgRmAnnot.

124 \newcommand{\fgRmAnnot}[2][]{\begingroup
125  \@ifundefined{#2@fdgdigis}%
126  {\PackageError{fldigigal}{The name `#2' is not defined
127  for\MessageBreak this \string\fgRmAnnot}{Gallery names
128  are defined using \string\fdgXmlList}}%

We get the key-value pairs for the fgRmAnnot family, then within the galleryopts key, we process those options as well.

129  \setkeys*{fgRmAnnot}{#1}\edef\XKV@rm@saved{\XKV@rm}%
130  \edef\tmp@setkeysEx{\noexpand\setkeys{fgGalleryOpts}%
131  {\fgRmAnnot@galleryopts}}\tmp@setkeysEx

We build part of the flashvars that correspond to this application. The macro \merged@flashvars merges the flash variables entered directly by the document author to control the \rmAnnot.

132  \edef\merged@flashvars{\fgRmAnnot@flashvars%
133  \ifKV@fgGalleryOpts@auto\else&%
134  auto=\fgGalleryOpts@auto\fi
135  \ifx\fgGalleryOpts@delay\@empty\else&%
136  delay=\fgGalleryOpts@delay\fi
137  \ifx\fgGalleryOpts@trans\@empty\else&%
138  transitionType=\fgGalleryOpts@trans\fi
139  \ifKV@fgGalleryOpts@transOn\else&%
140  transitionOn=\fgGalleryOpts@transOn\fi
141  \ifx\fgGalleryOpts@captionalign\@empty\else&%
142  captionalign=\fgGalleryOpts@captionalign\fi
143  \ifKV@fgGalleryOpts@nocaptions&%
144  nocaptions=\fgGalleryOpts@nocaptions%
145  \ifx\gGalleryOpts@nocaptionstext\@empty\else&%
146  nocaptionstext=\fgGalleryOpts@nocaptionstext\fi\fi

147 }%

OK, now we create an \rmAnnot with the desired parameters. We populate the

 flashvars key.
148  \rmAnnot[\XKV@rm@saved,
149  flashvars={xmlPath=\Name{\xmlListiv{#2}}\merged@flashvars},%
150  resources={\xmlListiv{#2}\embededResources{#2}}%
151  ]{320bp}{240bp}{\fgGalleryOpts@gallery}%
152  \endgroup

153 }

154 ⟨/package⟩