NAME

utility - ImageMagick Utility Routines


SYNOPSIS

AppendImageFormat(format,filename)

BaseFilename(name)

unicode=ConvertTextToUnicode(text,count)

ExpandFilename(filename)

status=ExpandFilenames(argc,argv)

FormatString(string,format,...)

GlobExpression(expression,pattern)

status=IsAccessible(filename)

status=IsDirectory(filename)

value=LSBFirstReadLong(file)

value=LSBFirstReadShort(file)

LSBFirstWriteLong(value,file)

LSBFirstWriteShort(value,file)

filelist=ListColors(pattern,number_colors)

filelist=ListFiles(directory,pattern,number_entries)

LocaleFilename(filename)

MSBFirstOrderLong(p,length);

value=MSBFirstReadLong(file)

value=MSBFirstReadShort(file)

MSBFirstWriteLong(value,file)

MSBFirstWriteShort(value,file)

geometry=PostscriptGeometry(page)

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

client_name=SetClientName(name)

argv=StringToArgv(text,argc)

list=StringToList(text)

Strip(data)

status=SystemCommand(verbose,command)

TemporaryFilename(filename)

TranslateText(image_info,image,text)


FUNCTION DESCRIPTIONS


AppendImageFormat

Method 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:

         AppendImageFormat(format,filename)

A description of each parameter follows.

format:

Specifies a pointer to an array of characters. This is the format of the image.

filename:

Specifies a pointer to an array of characters. The unique file name is returned in this array.


BaseFilename

Method 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 an character array that contains the name.


ConvertTextToUnicode

Method ConvertTextToUnicode converts an ASCII text string to Unicode and returns the Unicode translation and the character count. Normal characters are just copied. However, escaped hex codes are interpreted before converting to Unicode (e.g. \0x30a3 is 12451 in the Unicode character set).

The format of the ConvertTextToUnicode function is:

        unicode=ConvertTextToUnicode(text,count)

A description of each parameter follows:

unicode:

Method ConvertTextToUnicode returns a pointer to an unsigned short array representing the Unicode translation of the ASCII string.

text:

Specifies a pointer to an character array that contains the text to convert.

count:

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


ExpandFilename

Method ExpandFilename expands '~' in a filename.

The format of the ExpandFilename function is:

        ExpandFilename(filename)

A description of each parameter follows:

filename:

Specifies a pointer to an character array that contains the filename.


ExpandFilenames

Method ExpandFilenames checks each argument of the command line vector and expands 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:

Specifies a pointer to an integer describing the number of elements in the argument vector.

argv:

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


FormatString

Method 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:

Method FormatString returns the formatted string in this character buffer.

format:

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


GlobExpression

Method 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.


IsAccessible

Method 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:

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

filename:

Specifies a pointer to an array of characters. The unique file name is returned in this array.


IsDirectory

Method IsDirectory returns True if the file as defined by filename is a directory. 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:

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

filename:

Specifies a pointer to an array of characters. The unique file name is returned in this array.


ListColors

Method ListColors reads the X client color database and returns a list of colors contained in the database sorted in ascending alphabetic order.

The format of the ListColors function is:

        filelist=ListColors(pattern,number_colors)

A description of each parameter follows:

filelist:

Method ListColors returns a list of colors contained in the database. If the database cannot be read, a NULL list is returned.

pattern:

Specifies a pointer to a text string containing a pattern.

number_colors:

This integer returns the number of colors in the list.


ListFiles

Method ListFiles reads the directory specified and returns a list of filenames contained in the directory sorted in ascending alphabetic order.

The format of the ListFiles function is:

        filelist=ListFiles(directory,pattern,number_entries)

A description of each parameter follows:

filelist:

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

directory:

Specifies a pointer to a text string containing a directory name.

pattern:

Specifies a pointer to a text string containing a pattern.

number_entries:

This integer returns the number of filenames in the list.


LocaleFilename

Method LocaleFilename replaces the contents of the string pointed to by filename 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:

Specifies a pointer to an array of characters. The unique file name is returned in this array.


LSBFirstReadLong

Method 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:

Method LSBFirstReadLong returns an unsigned long read from the file.

file:

Specifies the file to read the data from.


LSBFirstReadShort

Method 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:

Method LSBFirstReadShort returns an unsigned short read from the file.

file:

Specifies the file to read the data from.


LSBFirstWriteLong

Method 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

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

The 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

Method 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

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

The 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

Method 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:

Method MSBFirstReadShort returns an unsigned short read from the file.

file:

Specifies the file to read the data from.


MSBFirstReadLong

Method 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:

Method MSBFirstReadLong returns an unsigned long read from the file.

file:

Specifies the file to read the data from.


MSBFirstWriteLong

Method 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

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

The 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.


MultilineCensus

Method 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

Method PostscriptGeometry replaces any page mneumonic with the equivalent size in picas.

The format of the PostscriptGeometry routine is:

         geometry=PostscriptGeometry(page)

A description of each parameter follows.

page:

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


ReadData

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

The format of the ReadData routine is:

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

A description of each parameter follows:

status:

Method ReadData returns True if all the data requested is obtained without error, otherwise False.

data:

Specifies an area to place the information reuested from the file.

size:

Specifies an integer representing the length of an individual item to be read from the file.

number_items:

Specifies an integer representing the number of items to read from the file.

file:

Specifies a file to read the data.


ReadDataBlock

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

The format of the ReadData routine is:

    status=ReadData(data,file)

A description of each parameter follows:

status:

Method ReadData returns the number of characters read unless there is an error, otherwise `-1'.

data:

Specifies an area to place the information reuested from the file.

file:

Specifies a file to read the data.


SetClientName

Method 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:

Method SetClientName returns the current client name.

status:

Specifies the new client name.


StringToArgv

Method 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:

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

text:

Specifies the string to segment into a list.

argc:

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


StringToList

Method StringToList converts a text string into a list by segmenting the text string at each carriage return discovered. The list is converted to HEX characters if any control characters are discovered within the text string.

The format of the StringToList routine is:

        list=StringToList(text)

A description of each parameter follows:

list:

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

text:

Specifies the string to segment into a list.


Strip

Method Strip strips the whitespace from the beginning and end of a string of characters.

The format of the Strip routine is:

       Strip(data)

A description of each parameter follows:

data:

Specifies an array of characters.


SystemCommand

Method SystemCommand executes the specified command and waits until it terminates. The returned value is the exit status of the command.

The format of the SystemCommand routine is:

        status=SystemCommand(verbose,command)

A description of each parameter follows:

status:

Method SystemCommand returns False if the command is executed successfully.

verbose:

An unsigned integer other than 0 prints the executed command before it is invoked.

command:

This string is the command to execute.


TemporaryFilename

Method TemporaryFilename replaces the contents of the string pointed to in their filenames.

The format of the TemporaryFilename routine is:

         TemporaryFilename(filename)

A description of each parameter follows.

filename:

Specifies a pointer to an array of characters. The unique file name is returned in this array.


TranslateText

Method TranslateText replaces any embedded formating characters with the appropriate image attribute and returns the translated text.

The format of the TranslateText routine is:

        TranslateText(image_info,image,text)

A description of each parameter follows:

image_info:

The address of a structure of type ImageInfo.

image:

The address of a structure of type Image.

text:

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