1XmPrintShell(library call) XmPrintShell(library call)
2
6 XmPrintShell — a shell widget class used for printing in Motif
7
9 #include <Xm/Print.h>
10 Boolean XmIsPrintShell(
11 Widget);
12
14 The XmPrintShell provides the Motif application programmer with an Xt
15 widget oriented API to some of the X Print resources and a callback to
16 drive the pagination.
17 The XmPrintShell provides a simple callback to handle the pagination
19 logic, and a set of resources to get and set common printer attributes.
20 If not created on an XPrint connection, XmPrintShell behaves as a regu‐
22 lar applicationShell.
23 The XmPrintShell also initializes the Xp extension event handling mech‐
25 anism, by registering an extension selector that calls XpSelectInput
26 and event dispatcher for print and attributes Xp events, so applica‐
27 tions can use XtInsertEventTypeHandler to register their own handler
28 with the Xp events.
29 Arguments
31 No XmCreate function is provided, since this is a toplevel shell, most
32 likely created thru some Xt shell creation routine or XmPrintSetup.
33 Classes
35 XmPrintShell is a subclass of ApplicationShell; it inherits behavior,
36 resources and traits from all its superclasses. The class pointer is
37 XmPrintShellWidgetClass.
38 New Resources
40 XmPrintShell Resource Set
41 Name Class Type Default Access
42 XmNstartJobCallback XmCCallback XtCallbackList NULL CSG
43 XmNendJobCallback XmCCallback XtCallbackList NULL CSG
44 XmNpageSetupCallback XmCCallback XtCallbackList NULL CSG
45 XmNminX XmCMinX Dimension dynamic G
46 XmNminY XmCMinY Dimension dynamic G
47 XmNmaxX XmCMaxX Dimension dynamic G
48 XmNmaxY XmCMaxY Dimension dynamic G
49 XmNdefaultPixmapResolution XmCDefaultPixmapResolution unsigned short 100 CSG
50 XmNpdmNotificationCallback XmCCallback XtCallbackList NULL CSG
51 XmNstartJobCallback
53 Specifies the callback driving the beginning of rendering.
54 It is safe for an application to start rendering after this
55 callback has been activated. XpStartJob must be called to
56 trigger this callback.
57 XmNendJobCallback
59 Specifies the callback driving the end of rendering. Notify
60 the client that all rendering has been processed (whether on
61 print-to-file or regular spool). XpEndJob is called by the
62 print shell to trigger this callback.
63 XmNpageSetupCallback
65 Specifies the callback driving the page layout. It is safe
66 for an app to start rendering from this callback even if the
67 XmNstartJobCallback is not used.
68 XmNminX, XmNminY, XmNmaxX, XmNmaxY
70 Specify the imageable area of the page in the current print
71 context. XmPrintShell also maintains a proper size at all
72 times by updating its own widget dimension whenever an
73 attribute, such as resolution or orientation, changes. It is
74 sized in its Initialize routine so that the application can
75 rely on a proper size before the first StartPage call is
76 issued.
77 XmNdefaultPixmapResolution
79 Indicates the resolution in dpi (dot per inch) of the image
80 files read and converted by Motif for the widget descendants
81 of this shell. It is used to determine a scaling ratio to be
82 applied to pixmap created thru regular pixmap/icon conversion
83 of the following Widget resources:
84 · XmLabel.label*Pixmap, XmIconG.*IconPixmap XmTog‐
86 gleB.selectPixmap, XmPushBG.armPixmap, XmIconG.*Icon‐
87 Mask, XmMessageBox.symbolPixmap, XmCon‐
88 tainer.*StatePixmap, ...
89 · Leaving out the pixmap resources being used for tiling
91 (XmNhighlightPixmap, XmNtopShadowPixmap, XmNbottomShad‐
92 owPixmap, XmNbackgroundPixmap, ...)
93 XmNpdmNotificationCallback
95 A callback notifying the application about the status of the
96 PDM (see XmPrintPopupPDM). A XmPrintShellCallbackStruct is
97 used, with reason:
98 · XmCR_PDM_NONE: no PDM available on this display for the
100 named selection (provided in detail)
101 · XmCR_PDM_START_VXAUTH : the PDM is not authorized to
103 connect to the video display.
104 · XmCR_PDM_START_PXAUTH : the PDM is not authorized to
106 connect to the print display.
107 · XmCR_PDM_UP : the PDM is up and running
109 · XmCR_PDM_OK : the PDM has exited with OK status
111 · XmCR_PDM_CANCEL : the PDM has exited with CANCEL
113 · XmCR_PDM_START_ERROR : the PDM cannot start due to some
115 error (usually logged)
116 · XmCR_PDM_EXIT_ERROR : the PDM has exited with an error
118 Callback Information
120 The XmNstartJobCallback, XmNendJobCallback, XmNpageSetupCallback and
121 XmNpdmNotificationCallback operate on a XmPrintShellCallbackStruct,
122 which is defined as follow:
123 typedef struct
125 {
126 int reason; /* XmCR_START_JOB, XmCR_END_JOB,
127 XmCR_PAGE_SETUP, XmCR_PDM_* */
128 XEvent *event;
129 XPContext print_context;
130 Boolean last_page; /* in_out */
131 XtPointer detail;
132 } XmPrintShellCallbackStruct;
133 Additional Behavior
135 The last_page field is only meaningful when the reason is
136 XmCR_PAGE_SETUP.
137 The page setup callback is called with last_page False to notify the
139 application that it has to get its internal layout state ready for the
140 next page. Typically, a widget based application will change the con‐
141 tent of a Label showing the page number, or scroll the content of the
142 Text widget.
143 When the application has processed its last page, it should set the
145 last_page field in the callback struct to True. The callback will be
146 called a last time after that with last_page False to notify the appli‐
147 cation that it can safely clean-up its internal state (e.g., destroy
148 widgets).
149 No drawing should occur from within the callback function in the appli‐
151 cation, this is an Exposure event-driven programming model where wid‐
152 gets render themselves from their expose methods.
153 The print shell calls XpStartPage after the pageSetupCallback returns,
155 and XpEndPage upon reception of StartPageNotify.
156
158 XmPrintShell can generate the following warnings:
159 · Not connected to a valid X Print Server: behavior undefined.
161 · Attempt to set an invalid resolution on a printer: %s
163 · Attempt to set an invalid orientation on a printer: %s
165
167 Not applicable
168
170 PrintOnePageCB(Widget pshell, XtPointer npages,
171 /*----------*/ XmPrintSetPageCBStruct psp)
172 {
173 static int cur_page = 0;
174 cur_page++;
175 if (! psp->last_page
177 && curPage > 1) /* no need to scroll for the first page */
178 {
179 XmTextScroll(ptext, prows); /* get ready for next page */
181 } else { /**** I'm done */
183 XtDestroyWidget(pshell);
185 XtCloseDisplay(XtDisplay(pshell));
186 }
187 if (cur_page == (int) n_pages) psp->last_page = True;
189 }
190 PrintOKCallback(...)
192 /*-------------*/
193 {
194 pshell = XmPrintSetup (widget, pbs->print_screen,
195 "Print", NULL, 0);
196 XpStartJob(XtDisplay(pshell), XPSpool);
198 /**** here I get the size of the shell, create my widget
200 hierarchy: a bulleting board, and then a text widget,
201 that I stuff with the video text widget buffer */
202 /* get the total number of pages to print */
204 /* same code as previous example to get n_pages */
205 /**** set up my print callback */
207 XtAddCallback(pshell, XmNpageSetUpCallback,
208 PrintOnePageCB, n_pages);
209 }
210 Examples of XmNdefaultPixmapResolution usage:
212 · An application reuses the same image sources it uses for the
214 video interface, in XBM, XPM, PNG ot JPEG, to layout on its
215 printed pages. In this case, scaling is seamless.
216 ! icon.xpm is 30x30 pixels
218 app*dialog.pushb.labelPixmap:icon.xpm
219 ! print is 400dpi
220 app.print*form.lab.labelPixmap:icon.xpm
221 ! 120x120 pixels on the paper (auto scaling)
222 · An application provides a new set of image files, for a given
224 printer resolution (say 300). It doesn't want automatic scaling
225 by the toolkit for that resolution, it wants scaling based on
226 these 300dpi images for higher resolution. It creates its print
227 shell inside using the name "printHiRes" and adds the following
228 in its resource file:
229 app.printHiRes.defaultPixmapResolution:300
231 ! icon300.xpm is 120x120 pixels
232 app.printHiRes*form.lab.labelPixmap:icon300.xpm
233 ! 120x120 pixels on the paper (no scaling)
234 This way a printer resolution of 600 will result in a scale of a 300
236 dpi image by 2 (dpi=600 divided by base=300), while a printer resolu‐
237 tion of 150 (using default print shell name "print") will use the 100
238 dpi icon scaled by 1.5 (dpi=150 divided by default base=100).
239
241 XmPrintSetup(3), XmRedisplayWidget(3), XmPrintToFile(3), XmPrintPopup‐
242 PDM(3)
243 XmPrintShell(library call)