{"id":163,"date":"2008-11-25T19:20:46","date_gmt":"2008-11-25T19:20:46","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/2008\/11\/25\/printing-in-a-deployed-application\/"},"modified":"2016-08-04T08:07:40","modified_gmt":"2016-08-04T13:07:40","slug":"printing-in-a-deployed-application","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2008\/11\/25\/printing-in-a-deployed-application\/","title":{"rendered":"Printing in a Deployed Application"},"content":{"rendered":"<div xmlns:mwsh=\"https:\/\/www.mathworks.com\/namespace\/mcode\/v1\/syntaxhighlight.dtd\" class=\"content\">\r\n   <introduction>\r\n      <p>This week guest blogger <a href=\"mailto:pwebb@mathworks.com\">Peter Webb<\/a> continues his series of deployment-related posts with an article describing how printing works in a deployed application.\r\n      <\/p>\r\n\r\n   <\/introduction>\r\n   <h3>Contents<\/h3>\r\n   <div>\r\n      <ul>\r\n         <li><a href=\"#1\">Introduction<\/a><\/li>\r\n         <li><a href=\"#2\">Two Kinds of Printing<\/a><\/li>\r\n         <li><a href=\"#4\">Printing Interactively in MATLAB<\/a><\/li>\r\n\r\n         <li><a href=\"#5\">Printing from a Deployed Application<\/a><\/li>\r\n         <li><a href=\"#6\">Figure Properties and Printing<\/a><\/li>\r\n         <li><a href=\"#7\">Three Major Differences<\/a><\/li>\r\n         <li><a href=\"#8\">Frequently Asked Questions<\/a><\/li>\r\n         <li><a href=\"#13\">The Future of Printing<\/a><\/li>\r\n         <li><a href=\"#14\">More to Come<\/a><\/li>\r\n\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Introduction<a name=\"1\"><\/a><\/h3>\r\n   <p>With this post, I hope to answer some long-standing and frequently asked questions about how a deployed application generates\r\n      hardcopy and why that process differs from printing in MATLAB. The differences are most evident in applications running under\r\n      Microsoft Windows; thus the bulk of this post concerns printing on Microsoft Windows. Most of these issues simply aren't issues\r\n      at all on the UNIX platforms.\r\n   <\/p>\r\n   <h3>Two Kinds of Printing<a name=\"2\"><\/a><\/h3>\r\n   <p>MATLAB's <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/print.html\"><tt>print<\/tt><\/a> command can send the graphics displayed in a figure window either to a file or a printer. MATLAB executes very different\r\n      code for when preparing graphics for these two destinations. Printing to a file is the simpler process, as it effectively\r\n      involves copying the pixels already displayed in the figure into a file on the disk. Printing to a printer requires MATLAB\r\n      to send instructions to the printer to regenerate the figure's pixels inside the printer.\r\n   <\/p>\r\n\r\n   <p>MATLAB figure windows render graphics using a mixture of C\/C++ functions and Java classes and methods. MATLAB's C\/C++ functions\r\n      invoke the native platform's graphical APIs directly; these C\/C++ functions comprise <i>native mode<\/i> Handle Graphics. MATLAB is evolving away from native mode graphics, because Java-based graphics are less platform-dependent,\r\n      but certain functions have not yet made the transistion. On the Microsoft Windows platform, printing figure windows still\r\n      requires calls to the native Windows API. UNIX platforms use Java, non-native mode, graphics to print.\r\n   <\/p>\r\n   <p>Why does all this matter? Because applications generated with the <a href=\"https:\/\/www.mathworks.com\/products\/compiler\">MATLAB Compiler<\/a> and the deployment tools cannot use native mode Handle Graphics. Without some kind of additional support, MATLAB applications deployed to computers\r\n      running Microsoft Windows would not be able to print. The MATLAB Compiler hides this complexity behind the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/toolbox\/compiler\/deployprint.html\"><tt>deployprint<\/tt><\/a> function, presenting a uniform API on both Microsoft Windows and UNIX systems. Deployed applications must use <tt>deployprint<\/tt> rather than <tt>print<\/tt> to send data to the printer:\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">    <span style=\"color: #0000FF\">if<\/span> ~isdeployed\r\n        print\r\n    <span style=\"color: #0000FF\">else<\/span>\r\n\r\n        deployprint\r\n    <span style=\"color: #0000FF\">end<\/span><\/pre><p>The <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/toolbox\/compiler\/isdeployed.html\"><tt>isdeployed<\/tt><\/a> function only returns true when executed by a deployed application.\r\n   <\/p>\r\n   <p>Note that <tt>deployprint<\/tt> cannot be used to print to a file, but only to send output to a printer. For printing to file, even in a deployed application,\r\n      use <tt>print<\/tt> instead.\r\n   <\/p>\r\n\r\n   <h3>Printing Interactively in MATLAB<a name=\"4\"><\/a><\/h3>\r\n   <p>In MATLAB, printing is a four step process. In each step, you interact with a single function or dialog box:<\/p>\r\n   <ol>\r\n   <li>Begin printing, specify figure to print: <tt>print<\/tt><\/li>\r\n   <li>Set MATLAB-specific print options: <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/printdlg.html\"><tt>printdlg<\/tt><\/a><\/li>\r\n   <li>Set platform-specific print options: the platform-specific print dialog box.<\/li>\r\n\r\n   <li>Send the data to the printer: the MATLAB <tt>Cancel Print Job<\/tt> dialog box.\r\n   <\/li>\r\n   <\/ol>\r\n   <p>Step 1 creates a <i>print job<\/i> and initializes it with default data. Steps 2 and 3 optionally modify the defaults. Step 4 reads the settings in the print\r\n      job and uses it to send image data and instructions to the printer. Together, these four steps make up the <i>printing pipeline<\/i>. In an interactive MATLAB session, MATLAB manages all four steps of the pipeline, but in a deployed application different\r\n      programs manage different parts of the pipeline.\r\n   <\/p>\r\n   <h3>Printing from a Deployed Application<a name=\"5\"><\/a><\/h3>\r\n\r\n   <p>When a deployed application prints, the printing pipeline has an additional step:<\/p>\r\n   <ol>\r\n   <li>Begin printing.<\/li>\r\n   <li>Set platform-specific print options.<\/li>\r\n   <li>Generate bitmap file from figure.<\/li>\r\n   <li>Set platform-specific print options.<\/li>\r\n   <li>Send data to the printer.<\/li>\r\n   <\/ol>\r\n\r\n   <p>The <tt>deployprint<\/tt> function manages the entire pipeline, but instead of using the Microsoft Windows printing API for the last two steps, as\r\n      <tt>print<\/tt> does, <tt>deployprint<\/tt> delegates this responsibility to a separate program, <tt>PrintImage.exe<\/tt>. Since <tt>PrintImage<\/tt> cannot directly access the figure window data, <tt>deployprint<\/tt> invokes <tt>print<\/tt> to create a Microsoft Windows bitmap from the figure, and passes the name of the bitmap file to <tt>PrintImage<\/tt>.\r\n   <\/p>\r\n\r\n   <p>Deployed applications use the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/toolbox\/compiler\/f12-999353.html\">MATLAB Common Runtime<\/a> (MCR) rather than MATLAB to execute MATLAB functions. MATLAB functions executed by the MCR produce exactly the same results\r\n      as when MATLAB executes those functions. However, <tt>PrintImage<\/tt> is not MATLAB, and though we've made every effort to duplicate MATLAB's behavior in <tt>PrintImage<\/tt> some differences are inevitable.\r\n   <\/p>\r\n   <p>In both MATLAB and deployed applications, <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f3-84337.html\">properties<\/a> stored on the figure window affect the printed appearence of the figure window. For example, the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/orient.html\"><tt>PaperOrientation<\/tt><\/a> property determines if the figure prints in landscape or portrait mode.\r\n   <\/p>\r\n\r\n   <h3>Figure Properties and Printing<a name=\"6\"><\/a><\/h3>\r\n   <p>In an interactive session, MATLAB processes all of the figure properties relevant to printing. In a deployed application,\r\n      the MCR processes all of the figure properties relevant to creating a bitmap (such as figure background color) and leaves\r\n      the properties that position the image on the page for <tt>PrintImage<\/tt> to process.\r\n   <\/p>\r\n   <p>Figure properties processed by <tt>PrintImage<\/tt>:\r\n   <\/p>\r\n   <div>\r\n      <ul>\r\n\r\n         <li><a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/orient.html\">PaperOrientation<\/a><\/li>\r\n         <li><a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f2-14338.html\">PaperPosition<\/a><\/li>\r\n         <li><a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f3-84337.html\">PaperSize<\/a><\/li>\r\n         <li><a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f3-84337.html\">PaperUnits<\/a><\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <p><tt>PrintImage<\/tt> endeavours to process these properties just as MATLAB would, but probably doesn't get it exactly right every time.\r\n   <\/p>\r\n\r\n   <p>In addition to specifying the position and orientation of the printed figure, you can use the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/printpreview.html\">print preview dialog box<\/a> to place header information on every printed page. In a deployed application, <tt>PrintImage<\/tt>, rather than MATLAB, processes the header data to produce the header text. Page header properties supported by <tt>PrintImage<\/tt>:\r\n   <\/p>\r\n   <div>\r\n      <ul>\r\n         <li>Date format<\/li>\r\n\r\n         <li>Font angle<\/li>\r\n         <li>Font name<\/li>\r\n         <li>Font size<\/li>\r\n         <li>Font weight<\/li>\r\n         <li>Margin<\/li>\r\n         <li>String<\/li>\r\n\r\n      <\/ul>\r\n   <\/div>\r\n   <p>Like it does with the figure properties, <tt>PrintImage<\/tt> attempts to process header text just as MATLAB does.\r\n   <\/p>\r\n   <h3>Three Major Differences<a name=\"7\"><\/a><\/h3>\r\n   <div>\r\n      <ul>\r\n\r\n         <li>Deployed applications print to a printer using <tt>deployprint<\/tt> and print to files using <tt>print<\/tt>. MATLAB uses a single function, <tt>print<\/tt>, for both types of printing.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <div>\r\n      <ul>\r\n\r\n         <li>Deployed applications print to a bitmap first, then send the bitmap to the printer. If the figure uses a vector renderer,\r\n            such as <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f3-103236.html\">Painters<\/a>, the printed output may differ visually from the graphics displayed in the figure. Deployed application always print using\r\n            a raster renderer.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <div>\r\n      <ul>\r\n         <li>Deployed applications format the figure data and the header text separately. The MCR renders the figure data to a bitmap,\r\n            and <tt>PrintImage<\/tt> superimposes the header text on the bitmap as it sends the bitmap to the printer. This may cause the header text to be placed\r\n            in a slightly different position on the page in a deployed application.\r\n         <\/li>\r\n\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Frequently Asked Questions<a name=\"8\"><\/a><\/h3>\r\n   <p><b>Can't the Compiler substitute <tt>deployprint<\/tt> for <tt>print<\/tt> at compile time?<\/b> No. The MATLAB Compiler, as a matter of policy, does not alter the executable code in any of the M-files that it packages\r\n      for deployment. In part, we established this policy to ensure that the MATLAB Compiler does not introduce any bugs into your\r\n      M-files, but we also recognize that this kind of substitution is impossible to implement with 100% accuracy. Calls to <tt>print<\/tt> could be hidden in strings passed to <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/eval.html\"><tt>eval<\/tt><\/a>, or in anonymous function handles or passed in as function parameters at runtime. Rather than make promises we couldn't keep,\r\n      we opted to require the use of <tt>isdeployed<\/tt> and <tt>deployprint<\/tt> as noted above.\r\n   <\/p>\r\n\r\n   <p><b>Why does <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/ref\/mlint.html\"><tt>mlint<\/tt><\/a> warn about printdlg?<\/b> This warning is out-of-date. In a future release it will be changed to indicate that deployed applications <i>do<\/i> support <tt>printdlg<\/tt>, but only the single-argument form of <tt>printdlg<\/tt>.\r\n   <\/p>\r\n   <p><b>Why can't I print (using <tt>deployprint<\/tt>) to PDFs?<\/b> Since <tt>deployprint<\/tt> uses <tt>print -dbmp<\/tt> to create the bitmap file, it explicitly ignores any output device specification passed in as an argument. However, you can\r\n      use <tt>print -dpdf<\/tt> to create a PDF file in your deployed applications. For example:\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">  <span style=\"color: #0000FF\">switch<\/span> KindOfPrinting\r\n      <span style=\"color: #0000FF\">case<\/span> <span style=\"color: #A020F0\">'Interactive'<\/span>\r\n\r\n          <span style=\"color: #0000FF\">if<\/span> ~isdeployed\r\n              print;\r\n          <span style=\"color: #0000FF\">else<\/span>\r\n              deployprint;\r\n          <span style=\"color: #0000FF\">end<\/span>\r\n      <span style=\"color: #0000FF\">case<\/span> <span style=\"color: #A020F0\">'ToFile'<\/span>\r\n          <span style=\"color: #228B22\">% Here, device should be a string such as 'pdf', and<\/span>\r\n\r\n          <span style=\"color: #228B22\">% outputFileName a name like 'output.pdf'.<\/span>\r\n          print([<span style=\"color: #A020F0\">'-d'<\/span> device], outputFileName);\r\n      <span style=\"color: #0000FF\">otherwise<\/span>\r\n          disp([<span style=\"color: #A020F0\">'Unrecognized printing mode: '<\/span> KindOfPrinting]);\r\n  <span style=\"color: #0000FF\">end<\/span><\/pre><p><b>Why do my figures look different when printed?<\/b> Printed output may differ from on-screen graphics if the figure uses the Painters renderer. You can ensure your on-screen\r\n      and printed graphics always use a raster renderer by setting the figure to use the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/techdoc\/creating_plots\/f3-103236.html\">Z-buffer<\/a> renderer:\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">  set(gcf, <span style=\"color: #A020F0\">'Renderer'<\/span>, <span style=\"color: #A020F0\">'zbuffer'<\/span>)<\/pre><p>Or, you can preview the appearence of your figures in a deployed application by printing them (in MATLAB) to a bitmap, and\r\n      then either viewing that bitmap on the screen or printing it. This command prints the current figure to a bitmap file named\r\n      <tt>myfig.bmp<\/tt>.\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">  print <span style=\"color: #A020F0\">-dbmp<\/span> <span style=\"color: #A020F0\">myfig.bmp<\/span><\/pre><p><b>How can I print from the menu bar or toolbar of a deployed application?<\/b> The default figure menu bar in a deployed application contains a single entry <tt>File<\/tt>. At the end of this menu is the selection <tt>Print...<\/tt>. Selecting <tt>Print...<\/tt> invokes <tt>deployprint<\/tt> and <tt>PrintImage<\/tt>. On the figure toolbar all deployed applications display a button containing a printer icon. Pressing this button sends the\r\n      associated figure to the printer using <tt>deployprint<\/tt> and <tt>PrintImage<\/tt>.\r\n   <\/p>\r\n\r\n   <p><b>How can I print from a shared library?<\/b> Either use the figure's menu or toolbar to print interactively, or write your own function that calls <tt>deployprint<\/tt> and include that function in your compiled application. For example, this <tt>myprint<\/tt> function sends the given figure (specified by figure number) to the given printer (specified by name):\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">  <span style=\"color: #0000FF\">function<\/span> myprint(fig, printer)\r\n    deployprint([<span style=\"color: #A020F0\">'-f'<\/span> num2str(fig)], [<span style=\"color: #A020F0\">'-P'<\/span> printer]);\r\n  <span style=\"color: #0000FF\">end<\/span><\/pre><p>If you create this function in <tt>myprint.m<\/tt> and add it to your compiled application, you'll be able to call the <tt>myprint<\/tt> function from whatever code you link your shared library against.\r\n   <\/p>\r\n\r\n   <h3>The Future of Printing<a name=\"13\"><\/a><\/h3>\r\n   <p>When MATLAB abandons native mode Handle Graphics entirely, and supports Java-based printing on Microsoft Windows, <tt>deployprint<\/tt> and <tt>PrintImage<\/tt> will no longer be necessary. <tt>deployprint<\/tt> will simply call <tt>print<\/tt> (as it does now on Unix systems), and the printing-related <tt>mlint<\/tt> warnings will be modified or eliminated. Until then, however, you'll likely want to keep a copy of this posting handy if\r\n      you deploy applications that target Microsoft Windows.\r\n   <\/p>\r\n\r\n   <h3>More to Come<a name=\"14\"><\/a><\/h3>\r\n   <p>Future posts will cover troubleshooting a deployed application (overcoming common failures), debugging and managing and\r\n      organizing your code for deployment; if you've got a topic you'd like to hear more about, please let me know. In the meantime,\r\n      you can refer to the <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2008b\/toolbox\/compiler\/bq6ae_n-1.html\">documentation<\/a> for the MATLAB Compiler or post follow-up questions <a href=\"https:\/\/blogs.mathworks.com\/loren\/?p=163#respond\">here<\/a>.\r\n   <\/p>\r\n","protected":false},"excerpt":{"rendered":"<p>\r\n   \r\n      This week guest blogger Peter Webb continues his series of deployment-related posts with an article describing how printing works in a deployed application.\r\n      \r\n\r\n   \r\n   Contents\r\n... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2008\/11\/25\/printing-in-a-deployed-application\/\">read more >><\/a><\/p>","protected":false},"author":39,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[24],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/163"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/users\/39"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/comments?post=163"}],"version-history":[{"count":1,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/163\/revisions"}],"predecessor-version":[{"id":1934,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/163\/revisions\/1934"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=163"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=163"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=163"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}