Associating a file format with signature bytes. Adobe FrameMaker 12.0
Advertisement
Advertisement
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
. . .
F_StringsT importFilters, exportFilters;
IntT i;
F_Printf(NULL, (StringT)"\n\n ###IMPORT FILTERS###\n\n"); importFilters = F_ApiGetStrings(0, FV_SessionId,
FP_ImportFilters); for (i=0; i < importFilters.len; i++)
F_Printf(NULL, (StringT)"%s\n", importFilters.val[i]);
F_Printf(NULL, (StringT)"\n\n ###EXPORT FILTERS###\n\n"); exportFilters = F_ApiGetStrings(0, FV_SessionId,
FP_ExportFilters); for (i=0; i < exportFilters.len; i++)
F_Printf(NULL, (StringT)"%s\n", exportFilters.val[i]);
F_ApiDeallocateStrings(&importFilters);
F_ApiDeallocateStrings(&exportFilters);
Associating a file format with signature bytes
Some file formats have signature bytes . Signature bytes are a set of bytes with a unique value and location in a particular file format. FrameMaker products can use signature bytes to automatically identify a file’s format. The documentation for the file format your client converts may contain information on the signature bytes for that format.
FrameMaker products allow you to associate a set of signature bytes with a specific file format. When the FrameMaker product opens a file containing the signature bytes, it assumes the file has the specified file format and calls the appropriate filter for that format. For more information on registering signature bytes, see the FDK Platform
Guide for your platform.
488 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
Graphic inset properties
The API represents each graphic inset with an
FO_Inset object. An
FO_Inset object has the properties common to all graphic objects. It also has some properties that are specific to graphic insets. The following table lists some of these properties.
Property
FP_InsetDpi
FP_InsetFile
FP_InsetIsFixedSize
FP_InsetIsFlippedSideways
Type
IntT
StringT
IntT
IntT
Meaning
Dots per inch (DPI). Indicates scale factor. It only applies to autosizing raster images.
Platform-specific pathname if the inset is an external inset, or a null string
(
""
) if it is internal. The pathname can be document-relative.
True if
FP_Width and
FP_Height are used for the graphic’s size.
False if autosize is used.
True if inset is flipped sideways.
In addition to the properties listed in the table above, each
FO_Inset object has special properties called facet s, which contain data describing the imported graphic.
Each
FO_Inset object must have at least one of the standard graphic inset facets listed in the following table.
Facet format
DCS Black
DCS Cyan
DCS Magenta
DCS Yellow
CGM
EPSI (Encapsulated PostScript)
FrameImage
FrameVector
GIF
MacPaint
FDK Programmer’s Guide 489
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
Facet format
PCX
TIFF
XWD
DIB
EMF
OLE
WMF (Windows Metafile)
FrameImage facets follow Sun raster image format. FrameVector facets follow a TIFF format. For a complete description of these formats, see the online MIF Reference manual.
If an inset doesn’t have one of the facet formats listed above, a FrameMaker product can use a filter to convert another format into FrameImage or FrameVector formats. For example, if the inset has an HPGL facet, the FrameMaker product can convert it into
FrameVector format.
A FrameMaker product uses an inset’s facets to display and print it. A FrameMaker product may use different facets to display and print a graphic. For example, the
When displaying an imported graphic, FrameMaker products use one of the following facet formats (in order of preference):
Native platform format (WMF)
FrameVector
FrameImage and other bitmap formats
TIFF
Other bitmap formats
When printing an imported graphic, FrameMaker products use one of the following facet formats (in order of preference):
EPSI (Encapsulated PostScript)
Native platform format (WMF)
FrameVector
TIFF
FrameImage and other bitmap formats
490 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
Unlike other properties, which are identified by numbers, facets are identified by names.
Instead of using
propIdent.num to identify a facet, the API sets
propIdent.num to
0 and sets
propIdent.name to the facet name. For more information on how the
In addition to the facets listed above, each
FO_Inset object can have several clientspecific facets. Client-specific facets contain information that your client uses. A clientspecific facet can contain a complete set of data, or just a pathname to an external data file or database. You must register the names of client-specific facets with the
FrameMaker product. A graphic inset can have as many client-specific facets as you want.
Facets can specify integer (
IntT
), metric (
MetricT
), or unsigned bytes (
F_UBytesT
) data. Facets, such as EPSI and FrameImage, that specify multiple characters or binary data are
F_UBytesT facets.
F_UBytesT is defined as: typedef struct {
UIntT len; /* The number of unsigned bytes */
UByteT *val; /* The facet data */
} F_UBytesT;
Internal and external graphic insets
There are two types of graphic insets: internal and external. You choose which type your client supports. Both types require a display and print facet and can have one or more client-specific facets.
Internal graphic insets
Internal graphic insets are wholly contained within a FrameMaker product document. If a graphic inset is internal, the
FO_Inset object’s
FP_InsetFile property is set to a null string (
""
). Internal graphic insets are generally more portable than external graphic insets.
To update an internal graphic inset, the user starts the FrameMaker product and initiates an event that the graphic inset editor monitors. For example, if the user double-clicks the inset, the graphic inset editor updates the inset by setting its facets.
FDK Programmer’s Guide 491
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
The following EPSI facet data describes the rectangle in Figure 12-1.
Figure 12-1 A graphic inset
UbyteT *epsFacet = "\
%!PS-Adobe-2.0 EPSF-2.0\n\
%%Pages:0\n\
%%BoundingBox: 0 0 18 18\n\
%%Creator: kurt\n\
%%CreationDate: Fri Oct 16 10:40:20 1992\n\
%%EndComments\n\
%%BeginPreview: 18 18 1 18\n\
%FFFFC0\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%000040\n\
%FFFFC0\n\
%%EndPreview\n\
%%EndProlog\n\
%%Page: \"one\" 1 0 0 moveto 18 0 rlineto 0 18 rlineto -18 0\ rlineto closepath 0 setgray\
1 setlinewidth stroke\
%%Trailer\n\
";
492 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
External graphic insets
External graphic insets are stored in an external file. The
FP_InsetFile property of an external graphic inset is set to a platform-specific filename that specifies the file. For information on converting platform-specific pathnames to platform-independent
(device-independent) pathnames, see Chapter 15, “Making I/O and Memory Calls
Users can update external graphic insets the same way they edit internal graphic insets.
Because external graphic inset data is not contained within the FrameMaker product document, users can also edit the inset with other applications besides a graphic inset editor.
To edit an external graphic inset from a FrameMaker product, the user opens the document and double-clicks the inset. The FrameMaker product launches the graphic inset editor, which updates the inset by editing the inset file.
Example
Suppose the user creates a bitmap inset with a graphic inset editor named
myeditor
.
The resulting
FO_Inset object’s property list and some of its properties are shown in
F_PropValsT len:
12 val: val[0] propIdent num: FP_InsetEditor name: NULL propVal valType: FT_String u sval:
myeditor val[1] propIdent num: FP_FrameParent name: NULL propVal valType: FT_Id u ival:
ID of frame containing the inset
Figure 12-2 The property list for a bitmap FO_Inset object val[2] propIdent num: 0 name: FrameImage propVal valType: FT_UBytes u
NULL
FDK Programmer’s Guide 493
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
The
u union for the FrameImage facet is
NULL
. The
F_PropValT structure for
F_UBytesT facets does not provide the facet data. It only serves as a placeholder, indicating that a facet exists. To get and set the data for
F_UBytesT facets, you must
follow special procedures, which are described in “Getting and setting facets” on page 497.
Setting up your client to create and modify graphic insets
To set up your client to create and modify graphic insets, do the following:
1 Register your client as an API client.
You must register your client and all the facets it uses. For information on registering
API clients, see the FDK Platform Guide for your platform.
2 Add an F_ApiMessage() callback to your client.
When the user clicks your client in the Inset Editors scroll list or double-clicks a graphic inset, the FrameMaker product calls
F_ApiMessage() from your client. Define
F_ApiMessage() as follows:
VoidT F_ApiMessage(StringT message, /* Not used for insets */
F_ObjHandleT docId, /* ID of document containing the inset */
F_ObjHandleT objId); /* The ID of the inset or 0 */
Responding to the user launching your inset editor
When the user launches your graphic inset editor by choosing it from the Inset Editors scroll list, the FrameMaker product calls the editor’s
F_ApiMessage() callback with
objId set to
0
. You can include code in
F_ApiMessage() that allows the user to create a graphic inset and add it to the Frame document when your editor is launched.
To insert a graphic inset, you add an
FO_AFrame object and resize it to accommodate the inset. Then you add an
FO_Inset object to the frame and set its properties as needed.
494 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
The following code adds an external graphic inset (described in the file
myinset.fi
) when the user chooses the editor ( myeditor
) from the Inset Editors scroll list:
. . .
VoidT F_ApiMessage(message, docId, objId)
StringT message;
F_ObjHandleT docId;
F_ObjHandleT objId; /* 0 if launched from scroll list. */
{
F_ObjHandleT afrmId, insetId;
F_TextRangeT tr; if (!objId) {
/* Code that allows user to create a graphic goes here. */
/* Get the text selection and add frame at the beginning. */ tr = F_ApiGetTextRange(FV_SessionId, docId,
FP_TextSelection); afrmId = F_ApiNewAnchoredObject(docId, FO_AFrame, &tr.beg);
/* Code to resize and position frame goes here. */
/* Add the inset to the frame and set its properties. */ insetId = F_ApiNewGraphicObject(docId, FO_Inset, afrmId);
F_ApiSetString(docId,insetId,FP_InsetFile,"/tmp/myinset.fi");
F_ApiSetString(docId,insetId,FP_InsetEditor,"myeditor");
}
}
. . .
Responding to the user double-clicking a graphic inset
When the user double-clicks a graphic inset for which the
FP_InsetEditor property specifies your graphic inset editor, the FrameMaker product calls the editor’s
F_ApiMessage() callback with
objId set to the inset’s ID. Include code in
F_ApiMessage() that allows the user to update the inset. If the inset is an internal inset, you update it by setting its facets.
Although your API graphic inset editor should respond when the user selects it from the
Inset Editors scroll list or when the user clicks a graphic inset, it can create or update insets at any time. For example, you may want to update a document’s insets whenever the user opens the document or chooses a particular menu item.
If a graphic inset is an external graphic inset, you update it by editing the file specified by
FP_InsetFile
. The FrameMaker product periodically refreshes external insets against the files that describe them. If you want to ensure that the inset is refreshed
FDK Programmer’s Guide 495
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes immediately, you must reset the
FO_Inset object’s
FP_InsetFile
,
FP_Height
, or
FP_Width property.
A FrameMaker product doesn’t call
F_ApiMessage() only when the user double-clicks a graphic inset. It also calls
F_ApiMessage() when the user clicks a hypertext marker. Therefore, make sure that the object specified by
objId is a graphic inset and not a hypertext marker.
For example, the following code updates a graphic inset when the user clicks it:
. . .
VoidT F_ApiMessage(message, docId, objId)
StringT message;
F_ObjHandleT docId;
F_ObjHandleT objId;
{ if (!objId) {
/* Code to create a new inset goes here. */
} else{
/* Make sure clicked object is a graphic inset. */ if (F_ApiGetObjectType(docId,objId) == FO_Inset){
/* Code to edit or update facets with
* F_ApiGet[PropertyType]ByName() and
* F_ApiSet[PropertyType]ByName() goes here.
*/
}
}
}
. . .
Getting and setting graphic inset properties
To get and set individual graphic inset properties identified by property numbers, you use
F_ApiGet PropertyType () and
F_ApiSet PropertyType () functions just as you would with any other object properties. For example, to get and set
FP_InsetDpi
, you use
F_ApiGetInt() and
F_ApiSetInt()
.
To get and set facets and
FO_Inset property lists, follow the procedures discussed in the following sections.
496 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
Getting and setting facets
To get and set facets, use the following functions.
To Use
Query an integer facet
Query a metric facet
Query an
F_UBytes facet
Set an integer facet
Set a metric facet
Set an
F_UBytes facet
F_ApiGetIntByName()
F_ApiGetMetricByName()
F_ApiGetUBytesByName()
F_ApiSetIntByName()
F_ApiSetMetricByName()
F_ApiSetUBytesByName()
The syntax for these functions is similar to other
F_ApiGet PropertyType () and
F_ApiSet PropertyType () functions, except that you must identify the property with a character string instead of an integer. For example, the syntax for
F_ApiGetUBytesByName() is:
F_UBytes *F_ApiGetUBytesByName(F_ObjHandleT docId,
F_ObjHandleT objId,
StringT *propName);
This argument docId objId propName
Means
The ID of the document containing the inset
The ID of the inset whose facet you want to query
The name of the facet to query
For the exact syntax of the functions that get and set facets, look up the functions in
Chapter 2, “FDK Function Reference,” of the FDK Programmer’s Reference.
Getting and setting facets takes an additional step not needed with other properties— committing the transaction. After executing a series of gets or sets for a graphic inset’s facets, commit the transaction by getting or setting a facet named
""
.
FDK Programmer’s Guide 497
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
For example, the following code gets two facets and commits the transaction:
. . .
IntT myInt, err;
MetricT myMetric;
F_ObjHandleT docId, insetId; myInt = F_ApiGetIntByName(docId, insetId, "myinteger.facet"); myMetric = F_ApiGetMetricByName(docId, insetId,
"mymetric.facet"); err = F_ApiGetIntByName(docId, insetId, "");
. . .
If you are setting facets, you commit the transaction by setting a facet named
""
. For example:
. . .
#define in (MetricT) (72 * 65536)
F_ObjHandleT docId, insetId;
F_ApiSetMetricByName(docId, insetId, "mymetric.facet", 2*in);
F_ApiSetIntByName(docId, insetId, "", 0); /* Commit */
. . .
To get and set
F_UBytesT facets, follow the special procedures described in the following sections.
498 FDK Programmer’s Guide
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
Getting an F_UBytesT facet
Because an
F_UBytesT facet can contain large amounts of data, it is not feasible to return all the data in a single array. Calling
F_ApiGetUBytesByName() returns only the next chunk of a facet’s data. To get all the data for an
F_UBytesT facet, you must call
F_ApiGetUBytesByName() repeatedly until
F_UBytesT.len is
0
. For example, the following code gets all the bytes in a facet named
my.facet
:
. . .
F_ObjHandleT docId, insetId;
F_UBytesT aUBytes; do { aUBytes = F_ApiGetUBytesByName(docId,insetId,"my.facet");
/* Code to do something with aUBytes goes here. */
} while (aUBytes.len)
F_ApiGetUBytesByName(docId,insetId,""); /* Commit transaction.*/
. . .
Setting an F_UBytesT facet
To set an
F_UBytesT facet that contains a relatively small chunk of data, you call
F_ApiSetUBytesByName() once. To set an
F_UBytesT facet that contains a large chunk of data, you must call
F_ApiSetUBytesByName() multiple times, passing a small chunk of data each time. The size of the data chunk you pass depends on the platform you are using. In general, if you use a larger size chunk, you can set the facet more quickly. However, if you use too large a size, you risk exceeding the interapplication communication mechanism’s capacity.
FDK Programmer’s Guide 499
1 5
U s i n g I m p o r t e d F i l e s a n d I n s e t s
Associating a file format with signature bytes
For example, to set the EPSI facet of a graphic inset to the contents of a file named mydata
, use the following code:
. . .
#include "fchannel.h"
#include "futils.h"
F_ObjHandleT docId, insetId, pageId, pFrameId;
F_UBytesT aUBytes;
UByteT buf[10 * 1024];
ChannelT channel;
FilePathT *path;
/* Create inset on page frame of current page. */ docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc); pageId = F_ApiGetId(FV_SessionId, docId, FP_CurrentPage); pFrameId = F_ApiGetId(docId, pageId, FP_PageFrame); insetId = F_ApiNewGraphicObject(docId, FO_Inset, pFrameId); path = F_PathNameToFilePath((StringT)"/tmp/mydata",
NULL, FDefaultPath); channel = F_ChannelOpen(path, "r"); do{ aUBytes.len = F_ChannelRead(buf, 1, sizeof(buf), channel); aUBytes.val = buf;
F_ApiSetUBytesByName(docId, insetId, "EPSI", &aUBytes);
} while (aUBytes.len);
/* Commit transaction. */
F_ApiSetIntByName(docId, insetId, "", 0);
. . .
Getting and setting an entire FO_Inset property list
To get and set the property list for an
FO_Inset object, you can use
F_ApiGetProps() and
F_ApiSetProps() as you would with any other object.
However, these functions don’t handle facets that contain
UBytesT data. In the property list that
F_ApiGetProps() returns, these facets are always
NULL
. If you construct a property list that contains
F_UBytesT data and pass it to
F_ApiSetProps()
,
F_ApiSetProps() sets
FA_errno to
FE_BadPropType
.
You must get and set facets that contain
UBytesT data with
F_ApiGetUBytesByName() and
F_ApiSetUBytesByName()
.
500 FDK Programmer’s Guide
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement