4utility - ImageMagick Utility Methods;/


NAME



%utility - ImageMagick Utility Methods




(

SYNOPSIS



8allocated_string=AllocateString(source)

3AppendImageFormat(format,filename)

#BaseFilename(name)

7status=CloneString(destination,source)

9unicode=ConvertTextToUnicode(text,count)

)ExpandFilename(filename)

2status=ExpandFilenames(argc,argv)

0FormatString(string,format,...)

Cflags=GetGeometry(image_geometry,x,y,width,height)

3GlobExpression(expression,pattern)

.status=IsAccessible(filename)

-status=IsDirectory(filename)

-value=LSBFirstReadLong(file)

.value=LSBFirstReadShort(file)

.LSBFirstWriteLong(value,file)

/LSBFirstWriteShort(value,file)

#Latin1Compare(p,q)

;filelist=ListColors(pattern,number_colors)

Efilelist=ListFiles(directory,pattern,number_entries)

)LocaleFilename(filename)

-MSBFirstOrderLong(p,length);

-value=MSBFirstReadLong(file)

.value=MSBFirstReadShort(file)

.MSBFirstWriteLong(value,file)

/MSBFirstWriteShort(value,file)

2geometry=PostscriptGeometry(page)

=status=ReadData(data,size,number_items,file)

0client_name=SetClientName(name)

-argv=StringToArgv(text,argc)

(list=StringToList(text)

Strip(data)

6status=SystemCommand(verbose,command)

,TemporaryFilename(filename)

Otranslated_text=TranslateText(image_info,image,formatted_text)




B

FUNCTION DESCRIPTIONS






4

AllocateString



IMethod AllocateString allocates memory for a string and copies the source0string to that memory location (and returns it).

,The format of the AllocateString routine is:

4

        allocated_string=AllocateString(source)


(A description of each parameter follows:

?
allocated_string:


:Method AllocateString returns a copy of the source string.

source:


A character string.






:

AppendImageFormat



JMethod AppendImageFormat appends the image format type to the filename. If=an extension to the file already exists, it is first removed.

/The format of the AppendImageFormat routine is:

0

         AppendImageFormat(format,filename)


(A description of each parameter follows.

format:


HSpecifies a pointer to an array of characters. This is the format of theimage."

filename:


FSpecifies a pointer to an array of characters. The unique file name isreturned in this array.






0

BaseFilename



GMethod BaseFilename removes the path name component and any extensions.

+The format of the BaseFilename function is:



        BaseFilename(name)


(A description of each parameter follows:


name:


@Specifies a pointer to a character array that contains the name.






.

CloneString



IMethod CloneString allocates memory for the destination string and copies*the source string to that memory location.

0The format of the (void) CloneString routine is:

3

        status=CloneString(destination,source)


(A description of each parameter follows:

status:


IMethod IsAccessible returns True is the string is cloned, otherwise False is returned.%

destination:


A pointer to a character string.

source:


A character string.






@

ConvertTextToUnicode



HMethod ConvertTextToUnicode converts an ASCII text string to Unicode andJreturns the Unicode translation and the character count. Normal charactersBare just copied. However, escaped hex codes are interpreted beforeKconverting to Unicode (e.g. \0x30a3 is 12451 in the Unicode character set).

3The format of the ConvertTextToUnicode function is:

5

        unicode=ConvertTextToUnicode(text,count)


(A description of each parameter follows:

!
unicode:


HMethod ConvertTextToUnicode returns a pointer to an unsigned short array9representing the Unicode translation of the ASCII string.

text:


KSpecifies a pointer to a character array that contains the text to convert.

count:


FThe number of characters that were translated from ASCII to Unicode is*returned in this unsigned integer pointer.






4

ExpandFilename



0Method ExpandFilename expands '~' in a filename.

-The format of the ExpandFilename function is:

%

        ExpandFilename(filename)


(A description of each parameter follows:

"
filename:


DSpecifies a pointer to a character array that contains the filename.






6

ExpandFilenames



JMethod ExpandFilenames checks each argument of the command line vector andFexpands it if they have a wildcard character. For example, *.jpg might&expand to: bird.jpg rose.jpg tiki.jpg.

.The format of the ExpandFilenames function is:

.

        status=ExpandFilenames(argc,argv)


(A description of each parameter follows:


argc:


JSpecifies a pointer to an integer describing the number of elements in theargument vector.

argv:


JSpecifies a pointer to a text array containing the command line arguments.






0

FormatString



HMethod FormatString prints formatted output of a variable argument list.

*The format of the FormatString routine is:

-

         FormatString(string,format,...)


(A description of each parameter follows.

string:


JMethod FormatString returns the formatted string in this character buffer.

format:


GA string describing the format to use to write the remaining arguments.






.

GetGeometry



IMethod GetGeometry parses a geometry specification and returns the width,Jheight, x, and y values. It also returns flags that indicates which of theIfour values (width, height, xoffset, yoffset) were located in the string,9and whether the x and y values are negative. In addition,

)The format of the GetGeometry routine is:

?

        flags=GetGeometry(image_geometry,x,y,width,height)


(A description of each parameter follows:


flags:


EMethod GetGeometry returns a bitmask that indicates which of the four+values were located in the geometry string.(

image_geometry:


ESpecifies a character string representing the geometry specification.

x,y:


IA pointer to an integer. The x and y offset as determined by the geometryspecification is returned here.&

width,height:


KA pointer to an unsigned integer. The width and height as determined by the(geometry specification is returned here.






4

GlobExpression



IMethod GlobExpression returns True if the expression matches the pattern.

-The format of the GlobExpression function is:

/

        GlobExpression(expression,pattern)


(A description of each parameter follows:

$
expression:


<Specifies a pointer to a text string containing a file name.!

pattern:


:Specifies a pointer to a text string containing a pattern.






0

IsAccessible



FMethod IsAccessible returns True if the file as defined by filename is accessible.

*The format of the IsAccessible routine is:

+

         status=IsAccessible(filename)


(A description of each parameter follows.

status:


FMethod IsAccessible returns True is the file as defined by filename is(accessible, otherwise False is returned."

filename:


FSpecifies a pointer to an array of characters. The unique file name isreturned in this array.






.

IsDirectory



GMethod IsDirectory returns True if the file as defined by filename is aHdirectory. Once MetroWerks write a stat(2) function, we can*remove the chdir(2) function.

*The format of the IsAccessible routine is:

*

         status=IsDirectory(filename)


(A description of each parameter follows.

status:


GMethod IsDirectory returns True is the file as defined by filename is a'directory, otherwise False is returned."

filename:


FSpecifies a pointer to an array of characters. The unique file name isreturned in this array.






2

Latin1Compare



KMethod Latin1Compare compares two null terminated Latin-1 strings, ignoringHcase differences, and returns an integer greater than, equal to, or lessKthan 0, according to whether first is lexicographically greater than, equalHto, or less than second. The two strings are assumed to be encoded using ISO 8859-1.

+The format of the Latin1Compare routine is:



        Latin1Compare(p,q)


(A description of each parameter follows:


p:


4A pointer to the string to convert to Latin1 string.

q:


4A pointer to the string to convert to Latin1 string.






,

ListColors



IMethod ListColors reads the X client color database and returns a list ofFcolors contained in the database sorted in ascending alphabetic order.

)The format of the ListColors function is:

7

        filelist=ListColors(pattern,number_colors)


(A description of each parameter follows:

"
filelist:


HMethod ListColors returns a list of colors contained in the database. If5the database cannot be read, a NULL list is returned.!

pattern:


:Specifies a pointer to a text string containing a pattern.'

number_colors:


6This integer returns the number of colors in the list.






*

ListFiles



DMethod ListFiles reads the directory specified and returns a list ofJfilenames contained in the directory sorted in ascending alphabetic order.

(The format of the ListFiles function is:

A

        filelist=ListFiles(directory,pattern,number_entries)


(A description of each parameter follows:

"
filelist:


KMethod ListFiles returns a list of filenames contained in the directory. IfEthe directory specified cannot be read or it is a file a NULL list is returned.#

directory:


ASpecifies a pointer to a text string containing a directory name.!

pattern:


:Specifies a pointer to a text string containing a pattern.(

number_entries:


9This integer returns the number of filenames in the list.






4

LocaleFilename



GMethod LocaleFilename replaces the contents of the string pointed to by9filename by a unique file name relative to the directory.

,The format of the LocaleFilename routine is:

&

         LocaleFilename(filename)


(A description of each parameter follows.

"
filename:


FSpecifies a pointer to an array of characters. The unique file name isreturned in this array.






8

LSBFirstReadLong



BMethod LSBFirstReadLong reads a long value as a 32 bit quantity in#least-significant byte first order.

.The format of the LSBFirstReadLong routine is:

*

         value=LSBFirstReadLong(file)


(A description of each parameter follows.


value:


DMethod LSBFirstReadLong returns an unsigned long read from the file.

file:


)Specifies the file to read the data from.






:

LSBFirstReadShort



DMethod LSBFirstReadShort reads a short value as a 16 bit quantity in#least-significant byte first order.

/The format of the LSBFirstReadShort routine is:

+

         value=LSBFirstReadShort(file)


(A description of each parameter follows.


value:


FMethod LSBFirstReadShort returns an unsigned short read from the file.

file:


)Specifies the file to read the data from.






:

LSBFirstWriteLong



DMethod LSBFirstWriteLong writes a long value as a 32 bit quantity in#least-significant byte first order.

/The format of the LSBFirstWriteLong routine is:

+

         LSBFirstWriteLong(value,file)


(A description of each parameter follows.


value:


Specifies the value to write.

file:


(Specifies the file to write the data to.






<

LSBFirstWriteShort



EMethod LSBFirstWriteShort writes a long value as a 16 bit quantity in#least-significant byte first order.

0The format of the LSBFirstWriteShort routine is:

,

         LSBFirstWriteShort(value,file)


(A description of each parameter follows.


value:


Specifies the value to write.

file:


(Specifies the file to write the data to.






:

MSBFirstOrderLong



JMethod MSBFirstOrderLong converts a least-significant byte first buffer of(integers to most-significant byte first.

/The format of the MSBFirstOrderLong routine is:

*

         MSBFirstOrderLong(p,length);


(A description of each parameter follows.


p:


,Specifies a pointer to a buffer of integers.

length:


#Specifies the length of the buffer.






<

MSBFirstOrderShort



KMethod MSBFirstOrderShort converts a least-significant byte first buffer of(integers to most-significant byte first.

0The format of the MSBFirstOrderShort routine is:

+

     MSBFirstOrderLongShort(p,length);


(A description of each parameter follows.


p:


,Specifies a pointer to a buffer of integers.

length:


#Specifies the length of the buffer.






:

MSBFirstReadShort



DMethod MSBFirstReadShort reads a short value as a 16 bit quantity in"most-significant byte first order.

/The format of the MSBFirstReadShort routine is:

+

         value=MSBFirstReadShort(file)


(A description of each parameter follows.


value:


FMethod MSBFirstReadShort returns an unsigned short read from the file.

file:


)Specifies the file to read the data from.






8

MSBFirstReadLong



BMethod MSBFirstReadLong reads a long value as a 32 bit quantity in"most-significant byte first order.

.The format of the MSBFirstReadLong routine is:

*

         value=MSBFirstReadLong(file)


(A description of each parameter follows.


value:


DMethod MSBFirstReadLong returns an unsigned long read from the file.

file:


)Specifies the file to read the data from.






:

MSBFirstWriteLong



DMethod MSBFirstWriteLong writes a long value as a 32 bit quantity in"most-significant byte first order.

/The format of the MSBFirstWriteLong routine is:

+

         MSBFirstWriteLong(value,file)


(A description of each parameter follows.


value:


Specifies the value to write.

file:


(Specifies the file to write the data to.






<

MSBFirstWriteShort



EMethod MSBFirstWriteShort writes a long value as a 16 bit quantity in"most-significant byte first order.

0The format of the MSBFirstWriteShort routine is:

,

         MSBFirstWriteShort(value,file)


(A description of each parameter follows.


value:


Specifies the value to write.

file:


(Specifies the file to write the data to.






6

MultilineCensus



IMethod MultilineCensus returns the number of lines within a label. A line!is represented by a \n character.

,The format of the MultilineCenus routine is:



     MultilineCenus(label)


(A description of each parameter follows.


label:


#This character string is the label.






<

PostscriptGeometry



IMethod PostscriptGeometry replaces any page mneumonic with the equivalentsize in picas.

0The format of the PostscriptGeometry routine is:

/

         geometry=PostscriptGeometry(page)


(A description of each parameter follows.


page:


ESpecifies a pointer to an array of characters. The string is either aBPostscript page name (e.g. A4) or a postscript page geometry (e.g.612x792+36+36).






(

ReadData



KMethod ReadData reads data from the image file and returns it. If it cannotJread the requested number of items, False is returned indicating an error.

&The format of the ReadData routine is:

9

        status=ReadData(data,size,number_items,file)


(A description of each parameter follows:

status:


JMethod ReadData returns True if all the data requested is obtained withouterror, otherwise False.

data:


CSpecifies an area to place the information requested from the file.

size:


HSpecifies an integer representing the length of an individual item to beread from the file.&

number_items:


FSpecifies an integer representing the number of items to read from thefile.

file:


"Specifies a file to read the data.






2

ReadDataBlock



GMethod ReadDataBlock reads data from the image file and returns it. The>amount of data is determined by first reading a count byte. IfIReadDataBlock cannot read the requested number of items, `-1' is returnedindicating an error.

&The format of the ReadData routine is:

#

    status=ReadData(data,file)


(A description of each parameter follows:

status:


HMethod ReadData returns the number of characters read unless there is anerror, otherwise `-1'.

data:


CSpecifies an area to place the information requested from the file.

file:


"Specifies a file to read the data.






2

SetClientName



CMethod SetClientName sets the client name if the name is specified..Otherwise the current client name is returned.

+The format of the SetClientName routine is:

,

        client_name=SetClientName(name)


(A description of each parameter follows:

%
client_name:


5Method SetClientName returns the current client name.

status:


Specifies the new client name.






0

StringToArgv



GMethod StringToArgv converts a text string into command line arguments.

*The format of the StringToArgv routine is:

)

        argv=StringToArgv(text,argc)


(A description of each parameter follows:


argv:


CMethod StringToArgv returns the string list unless an error occurs,otherwise NULL.

text:


,Specifies the string to segment into a list.

argc:


AThis integer pointer returns the number of arguments in the list.






0

StringToList



HMethod StringToList converts a text string into a list by segmenting theHtext string at each carriage return discovered. The list is converted toGHEX characters if any control characters are discovered within the textstring.

*The format of the StringToList routine is:

$

        list=StringToList(text)


(A description of each parameter follows:


list:


CMethod StringToList returns the string list unless an error occurs,otherwise NULL.

text:


,Specifies the string to segment into a list.






"

Strip



IMethod Strip strips the whitespace from the beginning and end of a stringof characters.

#The format of the Strip routine is:



       Strip(data)


(A description of each parameter follows:


data:


!Specifies an array of characters.






2

SystemCommand



FMethod SystemCommand executes the specified command and waits until itAterminates. The returned value is the exit status of the command.

+The format of the SystemCommand routine is:

2

        status=SystemCommand(verbose,command)


(A description of each parameter follows:

status:


KMethod SystemCommand returns False if the command is executed successfully.!

verbose:


IAn unsigned integer other than 0 prints the executed command before it isinvoked.!

command:


&This string is the command to execute.






:

TemporaryFilename



JMethod TemporaryFilename replaces the contents of the string pointed to intheir filenames.

/The format of the TemporaryFilename routine is:

)

         TemporaryFilename(filename)


(A description of each parameter follows.

"
filename:


FSpecifies a pointer to an array of characters. The unique file name isreturned in this array.






2

TranslateText



IMethod TranslateText replaces any embedded formatting characters with the<appropriate image attribute and returns the translated text.

+The format of the TranslateText routine is:

K

        translated_text=TranslateText(image_info,image,formatted_text)


(A description of each parameter follows:

)
translated_text:


8Method TranslateText returns the translated text string.$

image_info:


-The address of a structure of type ImageInfo.

image:


)The address of a structure of type Image.(

formatted_text:


DThe address of a character string containing the embedded formatting characters.